PGPLOT Module: PGOPEN -- open a graphics device


INTEGER FUNCTION PGOPEN (DEVICE)
CHARACTER*(*) DEVICE

Open a graphics device for PGPLOT output. If the device is
opened successfully, it becomes the selected device to which
graphics output is directed until another device is selected
with PGSLCT or the device is closed with PGCLOS.

The value returned by PGOPEN should be tested to ensure that
the device was opened successfully, e.g.,

ISTAT = PGOPEN('plot.ps/PS')
IF (ISTAT .LE. 0 ) STOP

Note that PGOPEN must be declared INTEGER in the calling program.

The DEVICE argument is a character constant or variable; its value
should be one of the following:

(1) A complete device specification of the form 'device/type' or
'file/type', where 'type' is one of the allowed PGPLOT device
types (installation-dependent) and 'device' or 'file' is the
name of a graphics device or disk file appropriate for this type.
The 'device' or 'file' may contain '/' characters; the final
'/' delimits the 'type'. If necessary to avoid ambiguity,
the 'device' part of the string may be enclosed in double
quotation marks.
(2) A device specification of the form '/type', where 'type' is one
of the allowed PGPLOT device types. PGPLOT supplies a default
file or device name appropriate for this device type.
(3) A device specification with '/type' omitted; in this case
the type is taken from the environment variable PGPLOT_TYPE,
if defined (e.g., setenv PGPLOT_TYPE PS). Because of possible
confusion with '/' in file-names, omitting the device type
in this way is not recommended.
(4) A blank string (' '); in this case, PGOPEN will use the value
of environment variable PGPLOT_DEV as the device specification,
or '/NULL' if the environment variable is undefined.
(5) A single question mark, with optional trailing spaces ('?'); in
this case, PGPLOT will prompt the user to supply the device
specification, with a prompt string of the form
'Graphics device/type (? to see list, default XXX):'
where 'XXX' is the default (value of environment variable
PGPLOT_DEV).
(6) A non-blank string in which the first character is a question
mark (e.g., '?Device: '); in this case, PGPLOT will prompt the
user to supply the device specification, using the supplied
string as the prompt (without the leading question mark but
including any trailing spaces).

In cases (5) and (6), the device specification is read from the
standard input. The user should respond to the prompt with a device
specification of the form (1), (2), or (3). If the user types a
question-mark in response to the prompt, a list of available device
types is displayed and the prompt is re-issued. If the user supplies
an invalid device specification, the prompt is re-issued. If the user
responds with an end-of-file character, e.g., ctrl-D in UNIX, program
execution is aborted; this avoids the possibility of an infinite
prompting loop. A programmer should avoid use of PGPLOT-prompting
if this behavior is not desirable.

The device type is case-insensitive (e.g., '/ps' and '/PS' are
equivalent). The device or file name may be case-sensitive in some
operating systems.

Examples of valid DEVICE arguments:

(1) 'plot.ps/ps', 'dir/plot.ps/ps', '"dir/plot.ps"/ps',
'user:[tjp.plots]plot.ps/PS'
(2) '/ps' (PGPLOT interprets this as 'pgplot.ps/ps')
(3) 'plot.ps' (if PGPLOT_TYPE is defined as 'ps', PGPLOT
interprets this as 'plot.ps/ps')
(4) ' ' (if PGPLOT_DEV is defined)
(5) '? '
(6) '?Device specification for PGPLOT: '

[This routine was added to PGPLOT in Version 5.1.0. Older programs
use PGBEG instead.]


Returns
PGOPEN : returns either a positive value, the
identifier of the graphics device for use with
PGSLCT, or a 0 or negative value indicating an
error. In the event of error a message is
written on the standard error unit.

Arguments
DEVICE (input) : the 'device specification' for the plot device
(see above).