ILL version 2.0, December 1996 (R.E. Ghosh)
An alphabetic ordered brief description of all the PGxxxx routines is also available
------------------------------------------------------------------------
Module: PGNOPN -- open a graphics device defined in an environment variable
------------------------------------------------------------------------
SUBROUTINE PGNOPN(IIDEV,NNAME,IER)
c
c Routines PGNOPN, PGNSEL, PGNEND
c
c *** The original ILL routines PGOPN3, PGSLCT, PGEND3
c (for versions of pgplot/49g-502 (REG 1993-5) were written
c to offer several simultaneously open devices. This feature has
c now been incorporated into PGPLOT from version 5.1 (1996-TJP)
c
c Introducing additional common blocks into the PGPLOT library
c entrains some modifications to the build files (e.g. VMS)
c and poses other problems with shared libraries. Now part of the
c job of using information for automatically printing, or checking
c whether devices have already been opened reverts to the
c library user, since, experience showed these ILL extensions
c were not much used in the past. Furthermore these routines will now
c also work in conjunction with "standard" PGPLOT libraries elsewhere,
c when used as external routines.
c
c Use of predefined environment variables have proved to be
c a very simple way of setting up program sets avoiding repetitive
c questions concerning plotting device characteristics.
c
c Current convention established is to define
c PGPLOT_ILL_DEV_1 as a screen device
c typically /XSERVE /MS /WIN /TEK /TK41(Tek+Colour) /KRM (Kermit)
c PGPLOT_ILL_DEV_2 as a hardcopy (usually via a file) device
c typically PostScript, Gif, HP-Laserjet/Inkjet
c PGPLOT_ILL_PPAGE is usually 2 pictures per page
c PGPLOT_ILL_RUNFIGDISP is a command string to start figdisp
c e.g setenv PGPLOT_ILL_RUNFIGDISP "/pgdisp -line 64"
c or for VMS this can be a command file - see PGRUNX
c PGPLOT_ILL_PRINT_CMD is a command string to print the file
c used in PGNEND
c
c PGNOPN
c
c A general purpose routine for ILL to open one of the typical
c devices in use at ILL, and defined in an environment variable.
c It is used in conjunction with PGSLCT (now incoporated in PGPLOT)
c BUT WITH A DIFFERENT CALL; Plotting devices are now closed with
c PGNEND, replacing PGEND3. PGRUNX is still called internally
c to simplify starting up new X-windows for xdisp.
c
c The environment variable PGPLOT_ILL_PPAGE, if set, is used
c for hardcopy to set the number of pictures per page. This
c serves at ILL to reduce the volume of output. It is assumed
c that pictures have an aspect ratio of 4:3 (w:h) and that set
c to 1, output is landscape, 2 output is 2 pictures in portrait
c etc.
c
c The standard PGPLOT drivers, having been written by several
c authors, do not have a consistent method for defining output
c characteristics, e.g. filename. This routine manages this
c aspect. The characteristics can still be overridden from outside
c the program after compilation and link by using the
c environment variable, but the graphical program author now
c has a way of controlling access in a uniform way. Usually
c screens have background and foreground colours reversed to
c offer black text on white backgrounds. The constraint, inevitably
c is that here only specific drivers have been addressed, though
c from a management viewpoint this has distinct advantages.
c
c The drivers used at ILL are typically limited to:
c /ps,/xserv,
c /xterm,/xdisp,/gi
c and for PCs
c /ms,/win,/ps,/hj,/gi
c
c SUBROUTINE VARIABLES
c
c IIDEV INTEGER IN use environment variable
c PGPLOT_ILL_DEV_idev
c
c NNAME CHARACTER IN for hardcopy - filename
c if name terminates with # this is
c replaced by a 3 digit sequence number.
c IER INTEGER OUT zero if no error, otherwise negative
c
------------------------------------------------------------------------
Module: PGNSEL -- selects device opened by PGNOPN
------------------------------------------------------------------------
ENTRY PGNSEL(IIDEV,LAST,IER)
*** Selects IIDEV as current device and gives error return
c IIDEV integer IN requested device number
c OUT set to 0 actual device
c LAST integer OUT previous device number
c IER integer OUT error if non-zero
ier=0
last=icur
if(irdev(iidev).gt.0) go to 800
798 ier=-1
write(str,799) iidev
799 format('PGNSEL - trying to select unopened unit',i4)
call grwarn(str)
return
800 if(iidev.eq.icur) return
idev=irdev(iidev)
call pgqid(last)
call pgslct(idev)
call pgqid(idev1)
if(idev1.eq.last) go to 798
c *** of select fails then the "last" if open, is the current dev
icur=iidev
return
c
c
c
------------------------------------------------------------------------
Module: PGNEND -- close a graphics device opened by PGNOPN
------------------------------------------------------------------------
PGNEND -- close a graphics device opened by PGNOPN
void cpgnend(int *iidev);
ENTRY PGNEND(IIDEV)
c *** closes open device, and if name is set, and
c environment variable PGPLOT_ILL_PRINT_CMD is defined
c file "name" uses this command to print it
c IDEV integer IN requested device number
c
------------------------------------------------------------------------
------------------------------------------------------------------------
Module: PGOPN3 -- opens up to three output devices
------------------------------------------------------------------------
SUBROUTINE PGOPN3 (IDEV, IER)
INTEGER IDEV, IER
ILL Contribution, January 1995 (R.E. Ghosh)
This routine, developed at ILL, is used in conjunction with PGSEL3 and
PGEND3, to open up to three output devices, which can be reselected
sequentially. This permits, for example, screen display of several
pictures, then, be reselecting a pre-opened PostScript unit, adding
draw instructions to an existing file.
To simplify repetitive use environment or LOGICAL (OpenVMS) variables
are used as follows:
PGPLOT_ILL_DEV_n is checked to open the appropriate device for
the nth plotting unit. If PostScript, and no filename has been specified
then a systematic name is generated ( pgplotmn.ps).
e.g. setenv PGPLOT_ILL_DEV_2 /vps
or DEFINE PGPLOT_ILL_DEV_2 "/vps"
If the device selected is /xdisp then the routine will use the string
PGPLOT_ILL_PGRUNFIGDISP to launch the X display handler pgdisp.
e.g. setenv PGPLOT_ILL_DEV_1 3/xdisp
setenv PGPLOT_ILL_PGRUNFIGDISP "~/pgdisp -line 64"
Note the picture identifier 3 in 3/xdisp is propagated by PGOPN3,
still permitting multiple windows to be opened.
PGPLOT_ILL_PPAGE is checked to determine how many pictures per
page should be written for the PostScript output
Arguments:
IDEV (input) : if 0, the program will attempt to open all three
devices named in the environment variables
PGPLOT_ILL_DEV_1
PGPLOT_ILL_DEV_2
PGPLOT_ILL_DEV_3
if 1,2 or 3 the program will only open a single
device
Typically 1 would be used for the screen, and 2
for PostScript
IER (output) : is returned as 0 if no errors have been encoutered,
otherwise -1 is returned
------------------------------------------------------------------------
Module: PGSEL3 -- reselects a plotting device opened by PGOPN3
------------------------------------------------------------------------
SUBROUTINE PGSEL3 (ID, LASTID, IER)
INTEGER ID, LASTID, IER
******* Renamed from PGSLCT December 1996 incompatible with PGPLOT511
ILL Contribution, January 1995 (R.E. Ghosh)
Once PGOPN3 has been used to open up to three output devices, these can
be reselected in turn by calling PGSEL3, which then reselects ID as
the new output unit. The previous active unit is returned to the
calling program simplifying a subsequent restore operation. If the
device has not been pre-opened successfully IER shows the error
condition.
Argument:
ID (input) : the number of the output device to be re-activated
(value 1,2 or 3).
LASTID (output) : the previously active output device (1,2 or 3)
IER (output) : error return is -1, otherwise success (0)
------------------------------------------------------------------------
Module: PGEND3(IDEV) -- terminate PGPLOT for devices opened by PGOPN3
------------------------------------------------------------------------
SUBROUTINE PGEND3 (IDEV)
INTEGER IDEV
ILL contribution, January 1995 (R.E. Ghosh)
Terminate PGPLOT, close the plot file, release the graphics
device. If the call to PGEND3 is omitted, some or all of the plot
may be lost. If the environment parameter PGPLOT_IDENT is defined
(with any value), and the device is a hardcopy device, an
identifying label is written on the plot (by calling PGIDEN: q.v.).
If the device is a PostScript file and the environment parameter
PGPLOT_ILL_PRINT_CMD is set, this string is used to spool the file
to the printer
e.g. setenv PGPLOT_ILL_PRINT_CMD "lpr -Plpps"
DEFINE PGPLOT_ILL_PRINT_CMD "PRINT/QUE=LRP1_ILL4"
See also PGOPN3, PGSEL3
Arguments:
IDEV (input) : if 0 then devices 1,2 and 3 are closed
if set to 1,2 or 3 then only that device is closed