%N pgopen %F $MIR/src/pgopen.f
%D Open a graphics device
%B
      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).
