Name:         PGBEG

Purpose:      open a graphics device

Category:     GRAPHICS

File:         pgplot.src

Author:       T.J. Pearson

Use:          see description below.

Description:

            INTEGER FUNCTION PGBEG (UNIT, FILE, NXSUB, NYSUB)
            INTEGER       UNIT
            CHARACTER*(*) FILE
            INTEGER       NXSUB, NYSUB
      
       Note: new programs should use PGOPEN rather than PGBEG. PGOPEN
       is retained for compatibility with existing programs. Unlike PGOPEN,
       PGBEG closes any graphics devices that are already open, so it 
       cannot be used to open devices to be used in parallel.
      
       PGBEG opens a graphical device or file and prepares it for
       subsequent plotting. A device must be opened with PGBEG or PGOPEN
       before any other calls to PGPLOT subroutines for the device.
      
       If any device  is already open for PGPLOT output, it is closed before
       the new device is opened.
      
       Returns:
        PGBEG         : a status return value. A value of 1 indicates
                          successful completion, any other value indicates
                          an error. In the event of error a message is
                          written on the standard error unit.  
                          To test the return value, call
                          PGBEG as a function, eg IER=PGBEG(...); note
                          that PGBEG must be declared INTEGER in the
                          calling program. Some Fortran compilers allow
                          you to use CALL PGBEG(...) and discard the
                          return value, but this is not standard Fortran.
       Arguments:
        UNIT  (input)   : this argument is ignored by PGBEG (use zero).
        FILE  (input)   : the "device specification" for the plot device.
                          (For explanation, see description of PGOPEN.)
        NXSUB  (input)  : the number of subdivisions of the view surface in
                          X (>0 or <0).
        NYSUB  (input)  : the number of subdivisions of the view surface in
                          Y (>0).
                          PGPLOT puts NXSUB x NYSUB graphs on each plot
                          page or screen; when the view surface is sub-
                          divided in this way, PGPAGE moves to the next
                          panel, not the  next physical page. If
                          NXSUB > 0, PGPLOT uses the panels in row
                          order; if <0, PGPLOT uses them in column order.

Updates:      Oct 16, 1998: JPT automatically extracted from source.