The DATA Step Graphics Interface

Using the DATA Step Graphics Interface

These sections provide general information about using DSGI.

To create graphics output using DSGI:

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

To use the DSGI interface:
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.

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

If you create 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 About GRSEGs 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, use the GSET("CATALOG", . . . ) function. This function enables you to specify the libref, and catalog name for the output catalog. Before you use the GSET("CATALOG", . . . ) function, assign a libref using the LIBNAME statement.

You can display DSGI graphics output stored in catalog entries multiple times, 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 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.

SAS/GRAPH Global Statements with DSGI

Some SAS/GRAPH global statements can be used with DSGI programs. DSGI recognizes FOOTNOTE, GOPTIONS, and TITLE statements. When TITLE and FOOTNOTE statements are used, the output from DSGI statements is placed in the procedure output area. See How Graphic Elements are Placed in the Graphics Output Area for an explanation of how space in graphics output is allocated to titles and footnotes.

Note: DSGI ignores AXIS, LEGEND, NOTE, PATTERN, and SYMBOL statements. [cautionend]

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=

Operating States

The operating state of DSGI determines which functions and routines can be issued at any point in the DATA step. You can submit a function or routine only when the operating state is appropriate. Reference How Operating States Control the Order of DSGI Statements for 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 can check the settings of the attributes.
SGOP	segment open. At this point, graphics output primitives can 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 a 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 might 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.

Top of Page