Chapter Contents

Previous

Next

Exporting SAS/GRAPH Output with Program Statements

When you use program statements to create external files for your SAS/GRAPH output, you use one of these processes:

• create one file that contains one graph

• create one file that contains multiple graphs

• create multiple files that each contain one graph.

You can send the graphics output to external files either at the time you run the program that creates the graphs, or later when you replay them from the catalog in which they are stored. For this reason, these methods are most useful for processing large quantities of output. In addition, using program statements allows you to specify exactly the device driver you want and is therefore a more flexible and powerful way of exporting SAS/GRAPH output.

The following sections provide some information common to all the processes and then describes each process in detail.

General Information

Common Requirements

Regardless of the process you use to create a GSF from a SAS/GRAPH program, you must specify the following:

• a destination for the output. This can be an aggregate file storage location (for example, a directory or a partitioned data set) or a specific file. Typically you specify the destination with a FILENAME statement and one or more graphics options. For more information, see FILENAME Statement.

• a device driver that creates the type of graphics output that you want.

• whether SAS/GRAPH should replace an existing file or append new records to it. By default, SAS/GRAPH replaces an existing file with newly created output of the same name. For details, see Replacing Existing External Files.

Each requirement is explained in detail in the individual process descriptions.

Naming the Output

When you are working with both catalog entries and external files, you should understand how both types of output are named.

Using the NAME= option

You can use the NAME= option in the SAS/GRAPH procedure to specify a name for the catalog entry that the procedure generates. How this name is used depends on whether the FILENAME statement points to a specific external file or to an aggregate file storage location.

• If you specify a specific filename for the external file and also use the NAME= option, the external file is assigned the name specified in the FILENAME statement and NAME= controls only the name given to the created catalog entry. When you specify the filename, you should include the appropriate file extension, such as .CGM, .GIF, or .PS).

• If you specify an aggregate file storage location instead of a specific filename, and also use the NAME= option, the name of the external file is built from the name of the catalog entry, which is determined by the value of NAME=. In this case, SAS/GRAPH supplies the appropriate file extension.

See How SAS/GRAPH Generates Entry Names and File Names for examples.

Using the default output name

If you omit NAME=, SAS/GRAPH uses the default naming convention to name the catalog entry, and in some cases the external file. This convention uses up to eight characters of the procedure name as the base name for the catalog entry. If the name generated by the procedure duplicates an existing entry, the name is incremented, for example, GCHART, GCHART1, GCHART2, and so forth. For details, see the description of the NAME= option for a specific procedure.

• If you specify a specific filename for the external file and omit the NAME= option, the external file uses the name specified in the FILENAME statement and the catalog entry uses the default name. When you specify the filename, you should include the appropriate file extension, such as .CGM, .GIF, or .PS.

• If you specify an aggregate file storage location instead of a specific filename, and omit the NAME= option, both the catalog entry and the external file use the default name and SAS/GRAPH supplies the appropriate file extension.

See How SAS/GRAPH Generates Entry Names and File Names for examples.

File extensions

When you send SAS/GRAPH output to an aggregate file storage location, SAS/GRAPH generates the name of the external file by taking the catalog entry name and adding the appropriate file extension. Most drivers provide a default extension. If a driver does not generate an extension, SAS/GRAPH uses the default extension .GSF. To specify a different extension from the one SAS/GRAPH provides, use the EXTENSION= graphics option. (For details, see EXTENSION=).

Example

illustrates how SAS/GRAPH generates names for catalog entries and external files, depending on 1) whether the NAME= option is used, and 2) on the fileref specification. This illustration assumes the GSLIDE procedure and DEV=GIF:

How SAS/GRAPH Generates Entry Names and File Names

If...	And...	Then
NAME='FRED'	fileref points to a file named 'MYSLIDE.GIF'	catalog entry name: FRED external file name: MYSLIDE.GIF
NAME='FRED'	fileref points to a storage location (for example, a directory)	catalog entry name: FRED external file name: FRED.GIF
NAME= (not specified)	fileref points to a file named 'MYSLIDE.GIF'	catalog entry name: GSLIDE external file name: MYSLIDE.GIF
NAME= (not specified)	fileref points to a storage location (for example, a directory)	catalog entry name: GSLIDE external file name: GSLIDE.GIF

Note:   When the fileref points to an aggregate file storage location, the name of the catalog entry always determines the name of the external file. It does not matter whether the catalog entry name is the default name or a name assigned by NAME=.  

CAUTION:

If the graph created by the program already exists in the catalog, a new catalog entry with an incremented name will be created and a new external file may be created rather than updating the existing file.   

Saving One Graph to a File

The simplest way to save one graph to a file is to use the FILENAME statement, the GSFNAME= graphics option, and the default setting GSFMODE=REPLACE to create one graphics stream file. These steps describe the general process:

1. Use a FILENAME statement to define a fileref for the external file where you want to send the output. The file name must be the complete physical name of the external file and should include a file extension that indicates what type of graphics file you are creating, for example .GIF for a GIF file.

2. Assign the fileref to the GSFNAME= graphics option.

3. Specify the device driver with the DEVICE= graphics option.

4. Use the default setting GSFMODE=REPLACE so that SAS/GRAPH produces only one graph per file (unless BY-group processing is in effect). Because REPLACE is the default setting, you can omit GSFMODE=.

5. Submit the SAS/GRAPH program.

Note: The GSF remains open while the SAS/GRAPH procedure is running. Be sure to end the procedure by submitting another procedure step, DATA step, or QUIT statement. To be really safe, you can submit a FILENAME fileref CLEAR; statement to explicitly close the GSF.

Operating Environment Information:   On certain systems, other graphics options may be required. For more information on creating a graphics stream file, refer to the SAS Help facility for SAS/GRAPH Device Drivers for your operating environment.   

Example

This example creates one GSF that contains one text slide created by a group of TITLE and FOOTNOTE statements and the GSLIDE procedure.

Define the fileref. The FILENAME statement associates the fileref GRAFOUT with the external file that is the destination for the GSF. The file extension .PS indicates that the graphics output is PostScript.

filename grafout 'mygraph.ps';

Specify graphics options for the GSF. RESET=ALL resets all global statements and graphics options. DEVICE= specifies a PostScript device driver. GSFNAME= assigns the fileref GRAFOUT as the destination for the GSF. GSFMODE=REPLACE (the default) causes the contents of the external file to be replaced each time the graphics procedure is run.

goptions reset=all
         device=pscolor
         gsfname=grafout
         gsfmode=replace
         ftext=swissb;

Produce one text slide. NAME= specifies the name that is assigned to the catalog entry created by the procedure. If you omit NAME=, SAS/GRAPH uses the default naming convention to name the entry.

proc gslide border name='proposal';
   title1 h=4 'Proposed Design Improvements:';
   title2 h=3 '* Increase Stability';
   title3 h=3 '* Increase Speed';
   title4 h=3 '* Reduce Weight';
   footnote h=2 j=l 'ABC Company';
run;
quit;

When you submit these statements, SAS/GRAPH does the following if no graphs of the same name exist in the catalog:

• Creates one catalog entry named PROPOSAL in WORK.GSEG.

• Creates one external file that contains the output from the GSLIDE procedure and sends a message to the LOG reporting the number of records and the name of the file to which they were written. The file name is the one specified in the FILENAME statement.

Because the destination is a specific file and because GSFMODE=REPLACE, each time you run the program it replaces the contents of the external file. Therefore, this method is particularly useful when you want to update an external file by resubmitting an existing program.

However, if there is more than one run of a graphics procedure in this program, the file would contain only the graphics output from the last procedure run because this program replaces the external file each time a graphics procedure is run.

Note:   Even though the contents of the external file are replaced, the catalog entry is not. Unless you explicitly delete the existing entry named PROPOSAL, each time you submit the program, a new entry is created and the catalog entry name is incremented. This table illustrates what happens if you submit the above program three times without deleting the catalog entries:  

Pass		Catalog entries	File name
1		PROPOSAL	mygraph.ps
2		PROPOSA1	mygraph.ps
3		PROPOSA2	mygraph.ps

Note that each new catalog entry replaces the contents of the external file, in this case, mygraph.ps. For more information, see Replacing Existing External Files.

For a complete description of the graphics options used in this example, see Graphics Options and Device Parameters Dictionary.

Saving Multiple Graphs to One File

If your program creates multiple graphs that you want to store in one file, you follow the same steps as those for saving one graph to one file except you specify GSFMODE=APPEND to add each new graph to the end of the file instead of replacing the file.

Example

This example stores several text slides in one external file. The program is the same as the previous example except the GOPTIONS statement specifies GSFMODE=APPEND and the GSLIDE procedure uses RUN-group processing to create multiple slides. Each slide includes the current TITLE statement and all previously defined TITLE and FOOTNOTE statements.

Define the fileref.

filename grafout 'mygraph.ps';

Specify graphics options for the GSF. GSFNAME= assigns the fileref GRAFOUT as the destination for the GSF. GSFMODE=APPEND adds each new piece of output to the end of the external file.

goptions reset=all
         device=pscolor
         gsfname=grafout
         gsfmode=append
         ftext=swissb
         rotate=landscape;

Produce four text slides. Each RUN-group generates a new catalog entry. NAME= specifies the base name for each catalog entry created by the procedure.

proc gslide border name='proposal';
   footnote h=2 j=l 'ABC Company';
   title1 h=4 'Proposed Design Improvements:';
run;
   title1 h=3 '* Increase Stability';
run;
   title1 h=3 '* Increase Speed';
run;
   title1 h=3 '* Reduce Weight';
run;
quit;

When you submit these statements, SAS/GRAPH does the following if no graphs of the same name exist in the catalog:

• Creates a new catalog entry for each graph, beginning with the name PROPOSAL. After the first graph is created, the entry name is incremented so that subsequent graphs are called PROPOSA1, PROPOSA2, and so forth.

• Creates one external file that contains all of the output from the GSLIDE procedure. The file name is the one specified in the FILENAME statement. Each time a graph is added to the file, SAS/GRAPH sends a message to the LOG reporting the number of records and the name of the file to which they were appended.

Note:   Because the destination is a specific file and because the GSFMODE= setting is APPEND, each time you run the program SAS/GRAPH adds the new graphs to the external file. If you want the file to contain only the newly created graphs, delete it before resubmitting the program.  

In addition, if you resubmit the program without deleting the original catalog entries, SAS/GRAPH will create four new entries that will be added to the catalog entry and four new graphs appended to the external file, both of which will contain all eight graphs.

This table illustrates what happens if you submit this program twice without deleting the catalog entries or the external file:

Pass		Catalog entries	File name	File contents
1		PROPOSAL PROPOSA1 PROPOSA2 PROPOSA3	mygraph.ps	PROPOSAL, PROPOSA1, PROPOSA2, PROPOSA3
2		PROPOSAL PROPOSA1 PROPOSA2 PROPOSA3 PROPOSA4 PROPOSA5 PROPOSA6 PROPOSA7	mygraph.ps	PROPOSAL, PROPOSA1, PROPOSA2, PROPOSA3, PROPOSA4,PROPOSA5, PROPOSA6, PROPOSA7

For more information, see Replacing Existing External Files.

Saving Multiple Graphs to Multiple Files

When you want your SAS/GRAPH program to create multiple files that each contain one graph, you can either

• use a FILENAME statements for each PROC statement to explicitly specify a destination file for each graph. To do this, simply repeat as many times as necessary the process described in Saving One Graph to a File.

• use one FILENAME statement to specify an aggregate file storage location as the destination and let SAS/GRAPH automatically name and create the files for you.

These steps describe the general process:

1. Use a FILENAME statement to define a fileref for the aggregate file storage location, such as a directory or PDS, where you want to send the output. Do not point to a specific file.

2. Assign the fileref to the GSFNAME= graphics option.

3. Specify the device driver with the DEVICE= graphics option.

4. Use the default setting GSFMODE=REPLACE so that SAS/GRAPH produces only one graph per file. Because REPLACE is the default setting, you can omit GSFMODE=.

5. Submit the SAS/GRAPH program.

Although the general technique is the same, there are significant differences between directing your graphics output to a specific file and directing it to an aggregate file storage location. These differences are mostly concerned with how the file is named.

When the destination is an aggregate file storage location, SAS/GRAPH not only creates the external file, it also names it. When SAS/GRAPH names an external file, it always uses the name of the entry in the output catalog. This name is either

• the name you specify in the NAME= option in the procedure

• the default name supplied by SAS/GRAPH, such as GSLIDE.

In addition, SAS/GRAPH automatically appends the correct file extension to the external file name. For example, if the output is named Q1SALES and the external file is a GIF file, the file name is Q1SALES.GIF.

This technique of building the file name from the catalog entry name affects what you do when you want to replace the contents of a file created in this way. For details, see Replacing Existing External Files.

Example

This example creates four text slides and stores each one in a separate external file. The program is similar to the previous examples except the fileref points to an aggregate storage location instead of to a specific file.

Define the fileref. The FILENAME statement assigns an aggregate file storage location as the destination for the files.

filename grafout 'external-file-location'; /* such as a directory */

Specify graphics options for the GSF. GSFNAME= assigns the fileref GRAFOUT as the destination for the GSF. GSFMODE=REPLACE (the default) replaces the contents of the external files with catalog entries of the same name.

goptions reset=all
         device=pscolor
         gsfname=grafout
         gsfmode=replace
         ftext=swissb
         rotate=landscape;

Produce four text slides. Each RUN-group generates a new catalog entry. NAME= specifies the base name for each catalog entry that is generated by the procedure. This name is also the base name for the external files.

proc gslide border name='proposal';
   footnote h=2 j=l 'ABC Company';
   title1 h=4 'Proposed Design Improvements:';
run;
   title1 h=3 '* Increase Stability';
run;
   title1 h=3 '* Increase Speed';
run;
   title1 h=3 '* Reduce Weight';
run;
quit;

When you submit these statements, SAS/GRAPH does the following if no graphs of the same name exist in the catalog:

• Creates a new catalog entry for each graph, beginning with the name PROPOSAL. After the first graph is created, the entry name is incremented so that subsequent graphs are called PROPOSA1, PROPOSA2, and so forth.

• Creates one external file for each catalog entry. The name of the file is the same as the entry name plus the extension. In this case, the files are named PROPOSAL.PS, PROPOSA1.PS, and so forth. For each file created, SAS/GRAPH sends a message to the LOG reporting the number of records and the name of the file to which they were written.

Note:   Because you cannot replace individual entries in a catalog, each time you run the program SAS/GRAPH creates new catalog entries and consequently new files. If you want to replace the files, you must delete the corresponding catalog entries before resubmitting the program.  

This table illustrates what happens if you submit this program twice without deleting the catalog entries:

Pass		Catalog entries	File name
1		PROPOSAL PROPOSA1 PROPOSA2 PROPOSA3	proposal.ps proposa1.ps proposa2.ps proposa3.ps
2		PROPOSA4 PROPOSA5 PROPOSA6 PROPOSA7	proposa4.ps proposa5.ps proposa6.ps proposa7.ps

Because the catalog names increment, there is never a matching file that the new catalog can replace. Therefore, unless you delete the existing entries, the program continues to create new files. To delete the existing entries, first run a GREPLAY procedure with the DELETE option:

proc greplay igout=work.gseg nofs;
   delete proposal proposa1 proposa2 proposa3;

Replacing Existing External Files

When you are working with aggregate file storage locations and automatic file naming, it is important to remember that GSFMODE=REPLACE replaces a file only if the name of the catalog entry is the same as the name of the file and you are using the same type of driver. For example, to replace a file named Q1SALES.PS, your program must create a catalog entry named Q1SALES, and you must also be using a PostScript driver. If the entry named Q1SALES already exists in the catalog, SAS/GRAPH will increment the name to Q1SALES1, and either create a new file with the incremented name or replace an existing file whose name matches the new incremented name.

Therefore, to replace the contents of existing external files with a new set of graphs, you must be sure that the catalog you are using does not already contain entries of the same name. There are several ways to assure that a catalog does not contain entries with the same names as your files:

• Use a temporary catalog, such as the default WORK.GSEG, to store the output and start a new SAS session. Initially, the catalog is empty.

• Use a temporary or permanent catalog and use the GREPLAY procedure to do either of the following:
  • delete the entire contents of the catalog before you submit your program

  • delete specified entries before you submit your program.

One additional method for replacing catalog entries is rarely recommended because it is easy to accidentally delete catalog entries that you did not intend to delete. If you want to replace the entire contents of the catalog and if you are running only one procedure, you can use the graphics option GOUTMODE=REPLACE. Whenever a new procedure starts, GOUTMODE=REPLACE replaces the entire contents of the current catalog with the new entries; it does not replace individual entries.

Example

The following example uses the GREPLAY procedure to explicitly delete specified catalog entries so that you can re-create them and replace the corresponding external files. This example uses the permanent catalog MYLIB.GRAFCAT.

• The GREPLAY procedure explicitly deletes existing catalog entries that have the same name as the entries to be created. If no entries exist, PROC GREPLAY issues a message and the program continues.

• The GSLIDE procedure generates four text slides and stores them in the catalog specified by GOUT=. NAME= specifies PROPOSAL as the base name for the catalog entries created by the procedure.

Define the libref for the permanent catalog.

libname mylib 'SAS-data-library';

Define the fileref. The FILENAME statement assigns an aggregate file storage location as the destination for the files.

filename grafout 'external-file-location';

Specify graphics options for the GSF. GSFNAME= assigns the fileref GRAFOUT as the destination for the GSF. GSFMODE=REPLACE (the default) replaces the contents of the external files with catalog entries of the same name.

goptions reset=all
         device=pscolor
         gsfname=grafout
         gsfmode=replace
         ftext=swissb
         rotate=landscape;

Delete existing catalog entries of the same name. The GREPLAY procedure deletes the specified catalog entries. These are the catalog names generated by the NAME= option in the procedure. If the entries do not exist, PROC GREPLAY issues a message and the program continues.

proc greplay nofs igout=mylib.grafcat;
   delete proposal proposa1 proposa2 proposa3;
run;

Produce four text slides. Each RUN-group generates a new catalog entry. NAME= specifies the base name for each catalog entry generated by the procedure. This name is also the base name for the external files.

proc gslide border gout=mylib.grafcat name='proposal';
   footnote h=2 j=l 'ABC Company';
run;
   title1 h=3 '* Increase Strength';
run;
   title1 h=3 '* Reduce Drag';
run;
   title1 h=3 '* Increase Resistance to Sheer';
run;
quit;

When you submit these statements, SAS/GRAPH does the following:

• deletes the specified entries from the catalog MYLIB.GRAFCAT.

• creates a new catalog entry in MYLIB.GRAFCAT for each slide, and increments the entry names: PROPOSAL, PROPOSA1, PROPOSA2, and PROPOSA3.

• creates one external file for each catalog entry. The file name is built from the catalog entry name. If a file of the same name already exists, SAS/GRAPH replaces the contents of the file.

Other Ways to Assign the Destination

You can use the GACCESS= graphics option to assign the destination for a graphics stream file. There are two ways to do this.

Using GACCESS=GSASFILE

This method is similar to the GSFNAME= method described in the previous sections.

• Use a FILENAME statement and assign a destination to the fileref GSASFILE. When you use GACCESS, the fileref must be named GSASFILE. The destination can be either a specific file or an aggregate file storage location.

• Assign GSASFILE to the GACCESS= graphics option instead of to GSFNAME=.

For example, these statements define and assign the fileref for an aggregate file storage location:

/* define a fileref for the destination  */
filename gsasfile 'external-file-location';

   /* assign the fileref and specify a device */
goptions reset=all gaccess=gsasfile device=gif;

Using GACCESS= to Explicitly Specify a Destination

You can also use GACCESS= to assign the destination and omit the FILENAME statement. In this case, you must also include the SASGASTD output format and quote the entire value. The destination can be either a specific file or an aggregate file storage location.

For example, this statement assigns a specific file location as the destination for the graphics stream file:

/* assign the fileref and specify a device */
goptions reset=all
  gaccess='sasgastd > my-graph-file.gif'
  device=gif;

Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.