| SAS/GRAPH Software: Reference |
When you
use program statements to create external files for
your SAS/GRAPH output, you use one
of these processes:
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.
Regardless of the
process you use to create a GSF from a SAS/GRAPH program,
you must specify the following:
Each requirement is explained in detail in the
individual
process descriptions.
When you are working with both
catalog entries
and external files, you should understand how both types of output are named.
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.
See How SAS/GRAPH Generates Entry Names and File Names
for examples.
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.
See How SAS/GRAPH Generates Entry Names and File Names
for examples.
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
the EXTENSION= graphics option. (For details, see EXTENSION=).
How SAS/GRAPH Generates Entry Names and File Names 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:
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=. ![[cautend]](../common/images/cautend.gif)
- 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.
You cannot replace individual entries in a catalog;
therefore, to replace an entry you must first delete the entry and then re-create
it. Therefore, even though the contents of the external file are replaced,
the catalog entry is not. Each time you submit the program, a new entry is
created and the catalog entry name is incremented.
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:
-
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.
-
Assign the fileref to the GSFNAME= graphics option.
-
Specify the device driver with the
DEVICE= graphics
option.
-
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=.
-
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.
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:
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:
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.
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.
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:
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.
When you want
your SAS/GRAPH program to create multiple
files that each contain one graph, you can either
These steps describe the general process:
-
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.
-
Assign the fileref to the GSFNAME= graphics option.
-
Specify
the device driver with the DEVICE= graphics
option.
-
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=.
-
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.
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:
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:
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;
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:
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.
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.
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:
You can use the GACCESS= graphics option to
assign the destination
for a graphics stream file. There are two ways to do this.
This method is
similar to
the GSFNAME= method described in the previous sections.
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;
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;
Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
