GRAPH Functions

GRAPH functions perform library management tasks from within the DATA Step Graphics Interface. These functions can only be performed on one catalog at a time. They cannot be performed across catalogs. For example, you cannot copy a graph from one catalog to another.

When using GRAPH functions, remember the following:

• All arguments are specified as variables or constants. If you express an argument as a variable, the variable must be initialized .

• All character arguments expressed as character strings must be enclosed in quotes.

• All character variable names used as arguments must be declared in a LENGTH statement.

• All character constants must be enclosed in single or double quotes.

GRAPH functions:

• CLEAR

• COPY

• DELETE

• INSERT

• PLAY

• RENAME

• UPDATE

CLEAR

Opens a graphics segment for output

Operating States: WSAC

Return Codes: 0, 3, 301, 302

Resulting Operating State: SGOP

Syntax

return-code-variable =GRAPH( CLEAR <, name > <, des ><, byline >);

Description

The GRAPH( CLEAR , ) function opens a graphics segment for output in the current catalog. The first parameter, CLEAR , is the only required one. The values of name , des , and byline are displayed in catalog listings and in catalog information in the GREPLAY procedure.

If the name specified is an existing graph, DSGI will suffix the name with a number. For example, if PIE is chosen for the name and it already exists, DSGI will name the output PIE1; the next time the code is submitted, DSGI names the output PIE2, and so forth.

This function moves the operating state from WSAC to SGOP.

Argument Definitions

name	character string enclosed in quotes or character variable name; gives a name to the graph to be opened. If name is not specified, DSGI assigns the graph a name that is some form of DSGI: for example, DSGI, DSGI1, and DSGI2.
des	character string enclosed in quotes or character variable name; gives a description to the graph to be opened. If des is not specified, DSGI assigns the following description to the catalog entry: Graph from DATA Step Graphics Interface.
by-line	character string enclosed in quotes or character variable name; gives another line of description for the graph. The byline appears under the titles on the graph. DSGI does not provide a default byline.

See Also

• OPENGRAPH on page 1428

• UPDATE on page 1461

COPY

Copies a graph

Operating States: GKOP, WSOP, WSAC, SGOP

Return Codes: 0, 8, 307

Syntax

return-code-variable =GRAPH( COPY , name, new-name) ;

Description

The GRAPH( COPY , ) function copies a graph to another catalog entry. The graph to be copied must be closed and be in the current catalog. You cannot copy from one catalog to another. The new graph will also be in the current catalog.

Argument Definitions

name	character string enclosed in quotes or character variable name; name of the graph to be copied.
new-name	character string enclosed in quotes or character variable name; name of the graph to be created.

See Also

• CATALOG on page 1407

• DELETE on page 1459

• INSERT on page 1459

• CATALOG on page 1465

DELETE

Deletes a graph

Operating States: GKOP, SGOP, WSAC, WSOP

Return Codes: 0, 4, 8, 307

Syntax

return-code-variable = GRAPH( DELETE , name );

Description

The GRAPH( DELETE , ) function deletes a graph in the current catalog. The graph does not have to be closed to be deleted.

Argument Definitions

name

character string enclosed in quotes or character variable name; the name of the graph to delete.

See Also

• CATALOG on page 1407

• COPY on page 1458

• CATALOG on page 1465

INSERT

Inserts a previously created segment into the currently open graph

Operating States: SGOP

Return Codes: 0, 4, 302, 307

Syntax

return-code-variable =GRAPH( INSERT , name );

Description

The GRAPH( INSERT , ) function inserts a graph into the currently open graph. The graph to be inserted must be closed and be in the current catalog.

Argument Definitions

name

character string enclosed in quotes or character variable name; the name of a graph to be inserted.

See Also

• CATALOG on page 1407

• COPY on page 1458

• CATALOG on page 1465

PLAY

Displays the specfied graph on your output

Operating States: GKOP, SGOP, WSAC, WSOP

Return Codes: 0, 307

Syntax

return-code-variable =GRAPH( PLAY , graph-name );

Description

The GRAPH( PLAY , ) function displays the specified graph on your output.

Argument Definitions

graph-name

character variable name; the name of the graph you would like to play.

See Also

• UPDATE on page 1461

RENAME

Renames a graph

Operating States: GKOP, SGOP, WSAC, WSOP

Return Codes: 0, 8, 307

Syntax

return-code-variable = GRAPH( RENAME , name, new-name );

Description

The GRAPH( RENAME , ) function renames a graph. The graph to be renamed must be in the current catalog and be closed.

Argument Definitions

name	character string enclosed in quotes or character variable name; the name of the closed graph that is to be changed.
new-name	character string enclosed in quotes or character variable name; the new name for the graph.

See Also

• CATALOG on page 1407

• INSERT on page 1459

• CATALOG on page 1465

UPDATE

Completes the currently open graph and ( optionally ) displays it

Operating States: SGOP

Return Codes: 0, 4

Resulting Operating State: WSAC

Syntax

return-code-variable = GRAPH( UPDATE <, show >);

Description

The GRAPH( UPDATE , ) function closes the graph currently open and displays it. DSGI operates in buffered mode, so the picture is never displayed until this function is called.

This function can be called only once for the currently open graph. Therefore, you cannot incrementally build a graph; however, you can close the currently open graph and later insert it into another graph within the same DATA step.

This function moves the operating state from SGOP to WSAC.

Argument Definitions

show

character string, optional; valid values are SHOW and NOSHOW. If SHOW is specified, the graph is displayed. If NOSHOW is specified, the graph is closed and not displayed.

See Also

• CLEAR on page 1457