SAS/GRAPH Software: Reference

Using the DATA Step Graphics Interface

The following sections provide general information about using DSGI, including general steps for using DSGI, how to produce and store graphs, how the data sets used with DSGI are structured, how SAS/GRAPH global statements can be used with DSGI, and how to debug DSGI programs. The sections also explain some of the basic concepts of DSGI, including information about operating states and windowing systems.

Summary of Use

To generate graphics output using DSGI, you generally follow these steps:

On a grid that matches the dimensions of the graphics output, sketch the output you want to produce.
Determine the coordinates of each graphics element.
In the DATA step, write the program to generate the graphics output. The basic steps are to
1. initialize DSGI
2. open a graphics segment
3. generate graphics elements
4. close the graphics segment
5. end DSGI.
Submit the DATA step with a final RUN statement to display the output.

Note: The DISPLAY graphics option must be in effect for the graphics output to be displayed. See Graphics Options and Device Parameters Dictionary for more information about the DISPLAY graphics option. [cautionend]

Producing and Storing DSGI Graphs

When you create or enhance graphs with DSGI, the DSGI graphics are displayed and stored as part of the graphics output. When you execute the DATA step, DSGI creates a catalog entry using the name from the GRAPH('CLEAR', . . . ) function.

By default, DSGI uses the name DSGI if you have not specified a name with the GRAPH('CLEAR', . . . ) function. By default, the catalog entry is stored in WORK.GSEG unless you specify another catalog with the GSET('CATALOG', . . . ) function.

If you generate another graph using a name that matches an existing catalog entry in the current catalog, DSGI uses the default naming conventions for the catalog entry. See Names and Descriptions of Catalog Entries for a description of the conventions used to name catalog entries.

If you want to store your output in a permanent library or in a different temporary catalog, you must use the GSET('CATALOG', . . . ) function. This function allows you to specify the libref and catalog name for the output catalog. Before you use the GSET('CATALOG', . . . ) function, you must allocate the libref using a LIBNAME statement.

You can redisplay DSGI graphics output stored in catalog entries using the GREPLAY procedure or the GRAPH window.

Structure of DSGI Data Sets

The DSGI DATA step is usually not written to produce an output data set. Unlike data sets created by the Annotate facility, which contain observations for each graphics element drawn, DSGI does not usually create an observation for each graphics primitive. Only variables created in the DATA step are written to the output data set.

You can output as many observations to the data set as you want. To output these values, you must use the OUTPUT statement. You can also use any other valid SAS DATA step statements in a DSGI DATA step. See SAS Language Reference: Dictionary for information about the statements used in the DATA step.

Using SAS/GRAPH Global Statements with DSGI

You can use some SAS/GRAPH global statements with DSGI programs. DSGI recognizes FOOTNOTE, GOPTIONS, and TITLE statements; however, it ignores AXIS, LEGEND, NOTE, PATTERN, and SYMBOL statements.

FOOTNOTE and TITLE statements affect DSGI graphics output the same way as they affect other SAS/GRAPH procedure output. When TITLE and FOOTNOTE statements are used, the output from DSGI statements is placed in the procedure output area. See Placement of Graphic Elements in the Graphics Output Area for an explanation of how space in graphics output is allocated to titles and footnotes.

Some DSGI functions override the graphics options. The following table lists the DSGI functions that directly override graphics options. For details about the graphics options, see Graphics Options and Device Parameters Dictionary.

DSGI Function Graphics Option That Is Overridden

GSET('CBACK', . . . ) CBACK=

GSET('COLREP', . . . ) COLORS=

GSET('DEVICE', . . . ) DEVICE=

GSET('HPOS', . . . ) HPOS=

GSET('HSIZE', . . . ) HSIZE=

GSET('VPOS', . . . ) VPOS=

GSET('VSIZE', . . . ) VSIZE=

GSET('TEXCOLOR', . . . ) CTEXT=

GSET('TEXFONT', . . . ) FTEXT=

GSET('TEXHEIGHT', . . . ) HTEXT=

DSGI Function	Graphics Option That Is Overridden
GSET('CBACK', . . . )	CBACK=
GSET('COLREP', . . . )	COLORS=
GSET('DEVICE', . . . )	DEVICE=
GSET('HPOS', . . . )	HPOS=
GSET('HSIZE', . . . )	HSIZE=
GSET('VPOS', . . . )	VPOS=
GSET('VSIZE', . . . )	VSIZE=
GSET('TEXCOLOR', . . . )	CTEXT=
GSET('TEXFONT', . . . )	FTEXT=
GSET('TEXHEIGHT', . . . )	HTEXT=

Operating States

The operating state of DSGI determines which functions and routines may be issued at any point in the DATA step. You can only submit a function or routine when the operating state is appropriate for it. See How Operating States Control the Order of DSGI Statements for a discussion of how functions and routines should be ordered within the operating states.

The operating states defined by DSGI are

GKCL facility closed, the initial state of DSGI. No graphical resources have been allocated.

GKOP facility open. When DSGI is open, you may check the settings of the attributes.

SGOP segment open. At this point, graphics output primitives may be generated.

WSAC workstation active. When the workstation is active, it can receive DSGI statements.

WSOP workstation open. In this implementation, the graphics catalog, either the default or the one specified through the GSET('CATALOG', . . . ) command, is opened or created.

Refer to individual functions and routines in DATA Step Graphics Interface Dictionary for the operating states from which that function or routine can be issued.

The Current Window System

When DSGI draws graphics, it evaluates x and y coordinates in terms of the current window system, either a window you have defined or the default window system. Unless you define and activate a different window, DSGI uses the default window system.

The default window system assigns two arbitrary systems of units to the x and y axes. The default window guarantees a range of 0 through 100 in one direction (usually the y direction) and at least 0 through 100 in the other (usually the x direction). The ranges depend on the dimensions of your device. You can use the GASK('WINDOW', . . . ) routine to determine the dimensions of your default window system.

You can define the x and y ranges to be any numeric range. For example, you can use - 1000 to +2000 on the x axis and 30 to 35 on the y axis. The units used are arbitrary.

Debugging DSGI Programs

When DSGI encounters an error in a program, it flags the statement in the SAS log and displays a description of the error. (To receive SAS System messages, GSET('MESSAGE', . . . ) must be ON.) The description provides you with an explanation of the error. The description may also provide a return code. If you get a return code, you can refer to Return Codes for DSGI Routines and Functions for a description of the error and why it might have occurred.

Some of the most common errors in DSGI programs are

syntax errors
an invalid number of arguments for the function or routine
a function or routine being executed in an operating state that is not correct for the function or routine.

Chapter Contents
Previous
Next
Top of Page

GKCL	facility closed, the initial state of DSGI. No graphical resources have been allocated.
GKOP	facility open. When DSGI is open, you may check the settings of the attributes.
SGOP	segment open. At this point, graphics output primitives may be generated.
WSAC	workstation active. When the workstation is active, it can receive DSGI statements.
WSOP	workstation open. In this implementation, the graphics catalog, either the default or the one specified through the GSET('CATALOG', . . . ) command, is opened or created.