install-vms.txt

PGPLOT Installation Instructions: VMS systems

Version 5.2.0

Note: The following instructions refer to two directories, the distribution
(source) directory which will contain the PGPLOT source code directory tree,
and the binary directory in which the machine-specific libraries, data
files, and demonstration programs will be created. It is recommended that
you create new, empty directories for these. They should not be the same
directory. In the examples below, these directories are named

USR:[LOCAL.PGPLOT] (distribution directory)
USR:[LOCAL.PGBIN] (binary directory)

but you can use any convenient names. Unusual (system) privileges are not
required to install PGPLOT, assuming you have write access to the
directories. In a mixed VAX-Alpha cluster, you can use a single distribution
directory, but you will need two binary directories, one for each
architecture. The distribution directory may be deleted after the
installation has been competed, but it will be needed if you later decide to
select different device drivers..

1. Copy the distribution file

Copy the distribution file by anonymous ftp from Caltech. Use anonymous ftp
(user: anonymous, password: your id username@machine) to node
astro.caltech.edu (131.215.240.1).

The distribution file is a UNIX tar file compressed with Gzip. Issue the
following ftp commands to retrieve the file:


        cd pub/pgplot
        binary
        get pgplot5.2.tar.gz pgplot.tar-gz

(Note that you need to provide a VMS-compatible output file name in the get
command.)

2. Decompress the files

You will need two programs to decompress and extract the contents of the
distribution file: gunzip and vmstar. These programs are not part of VMS,
but are widely available on the Internet, e.g., at

http://www.openvms.digital.com/openvms/freeware/cd.html

Use gunzip to decompress the distribution file, e.g.,

        $ gunzip pgplot.tar-gz

Then use vmstar to extract the contents of the archive:

        $ set default USR:[LOCAL}
        $ vmstar/extract/verbose pgplot.tar
 OR     $ vmstar xvf pgplot.tar
        $ delete pgplot.tar;

This will create a subdirectory [.PGPLOT] (and lower-level subdirectories)
in the current directory, e.g., USR:[LOCAL.PGPLOT...]. Make sure that your
current directory is where you want to create the ``PGPLOT distribution''
directory tree.

3. Create the binary directory

Create a writable directory in which the PGPLOT library and associated files
will be created. One such directory is needed for each different binary
system; e.g., you may want separate directories for VAX and Alpha.

        $ create/directory USR:[LOCAL.PGBIN]
        $ set default USR:[LOCAL.PGBIN]

Do not try to create the PGPLOT library in the source (``distribution'')
directory.

4. Select device drivers

Configure PGPLOT by selecting device drivers from the available list. First
copy the file drivers.list from the distribution directory to the binary
directory, and then use a text editor to select device drivers. This file
contains one line for each available device driver: delete the exclamation
mark (!) at the beginning of the line to include the driver, or ensure that
an exclamation mark is present if you want to exclude the driver. Many of
the drivers can be used only on certain operating systems (see notes in
drivers.list), so include only the drivers you plan to use. PGPLOT can later
be reconfigured by restarting the installation at this step. Most
installations should include: the null device (/NULL), PostScript printers
(/PS, /VPS, /CPS, and /VCPS), Tektronix terminals (/TEK, /XTERM, and
possibly other variants), and, if the X window system (DECwindows) is
available, the X window drivers (/XWIN, /XSERV). You may also wish to
include drivers for GIF files (/GIF, /VGIF) or some of the other printers.

        $ copy USR:[LOCAL.PGPLOT]drivers.list []
        $ edit drivers.list

5. Compile the library and demonstration programs

Execute the script install.com from the VMS subdirectory of the distribution
directory, e.g.:

        $ @USR:[LOCAL.PGPLOT.SYS_VMS]install USR:[LOCAL.PGPLOT]

The first argument supplied to install is the name of the distribution
directory. The script will attempt to determine your machine architecture
(VAX or Alpha) and compile appropriate code. The script has been tested
under several versions of VMS, but if you have problems, you may need to
edit the script.

The install script issues messages as it proceeds: it usually takes quite a
long time. It should generate the following files:

        DRIVERS.LIST
        GREXEC.F
        GRFONT.DAT
        GRPCKG.OLB
        GRPSHR.EXE
        GRPSHR.OLB
        PGDEMO1.EXE ... PGDEMO16.EXE
        PGXWIN_SERVER.EXE
        RGB.TXT

The script assumes that you have the current DEC Fortran and C compilers
installed. A C compiler is required for XWDRIV and X2DRIV and the associated
programs PGXWIN_SERVER and PGDISP, and for generating the C wrapper library
CPGPLOT.OLB. If you don't have the DEC C compiler, the script will have to
be modified.

The script may fail if you redefine any of the common DCL commands like
PURGE or DELETE.

Note: Demonstration program pgdemo14 is compiled incorrectly by the DEC
Fortran 6.2 compiler when optimization is enabled; the symptom is that the
labels like "Number of Vertices:" do not appear on the screen. The problem
is solved by disabling optimization.

6. Compile the optional components

C wrapper library

To install the optional C wrapper library, proceed as follows.

        $ @USR:[LOCAL.PGPLOT.SYS_VMS]install USR:[LOCAL.PGPLOT] CPG

This creates three files:

        CPGPLOT.H       (ANSI C header file)
        CPGPLOT.OLB     (library containing the C binding)
        CPGDEMO.EXE     (demonstration program)

PGDISP program

The PGDISP program is required if you selected the /XDISP device driver. Use
of this driver is not recommended: you should use the standard X Window
driver (/XWIN or /XSERV) instead.

        $ @USR:[LOCAL.PGPLOT.SYS_VMS]install USR:[LOCAL.PGPLOT] PGDISP

This adds one file, PGDISP.EXE. The PGDISP program sometimes gives
compilation problems. Most of these are non-fatal warnings that can be
ignored.

Motif support and example files

If you plan to develop Motif applications that use the PGPLOT widget, or if
you want to inspect a sample Motif application, you will need to do this
step. You must first: (a) ensure that the Motif header files and libraries
are installed on your system; (b) select XMDRIV in drivers.list before
installing the PGPLOT library; and (c) install the C wrapper library.
Execute the following command:

        $ @USR:[LOCAL.PGPLOT.SYS_VMS]install USR:[LOCAL.PGPLOT] PGMDEMO

This creates five files:

        PGMDEMO.EXE     (executable demo program)
        PGMOTIF.OPT     (linker options file for linking PGPLOT/Motif applications)
        PGXWIN.OBJ      (object module required by PGPLOT/Motif applications)
        XMPGPLOT.OBJ    (object module required by PGPLOT/Motif applications)
        XMPGPLOT.H      (header file required by PGPLOT/Motif applications)

(This step may not work on all VMS systems: there are many differences
between the various available versions of the DEC C compiler and DECwindows
Motif. If you get error messages, you may need to modify file
[local.pgplot.sys_vms]make_pgmdemo.com.)

7. Define logical names

Before running any PGPLOT program, you must ensure that the following
logical names are correctly defined. The logical names may be placed in the
process table or the system table. It may be convenient to place the
definitions in LOGIN.COM.

GRPSHR
     This should point to the PGPLOT shared library, GRPSHR.EXE, with
     complete directory information, e.g.,

           $ define GRPSHR PGPLOT_DIR:GRPSHR.EXE

     If this logical name is not defined, RUN will look for GRPSHR.EXE in
     the system library directory (SYS$LIBRARY).

PGPLOT_DIR
     This is the name of the directory in which PGPLOT will look for the
     files grfont.dat and rgb.txt (unless logical names PGPLOT_FONT and
     PGPLOT_RGB are defined to override this default behavior), and, if
     needed, the X-window server program pgxwin_server:

             $ define PGPLOT_DIR USR:[LOCAL.PGBIN]

PGPLOT_DEV
     It is also convenient, but not essential, to define a default PGPLOT
     device with logical name PGPLOT_DEV, e.g.

             $ define PGPLOT_DEV      "/xwin"

LNK$LIBRARY
     If you develop PGPLOT programs, you can arrange for the linker to
     automatically scan the PGPLOT library by naming GRPSHR.OLB in one of
     the LNK$LIBRARY* logical names, e.g.

           $ define LNK$LIBRARY PGPLOT_DIR:GRPSHR.OLB

     If you do not do this, you will need to include this library (note:
     GRPSHR.OLB, not GRPSHR.EXE) in your LINK commands.

Other PGPLOT logical names (environment variables) are described in the
manual.

8. Run the demonstration programs

Run the demonstration programs on your selected devices and verify that they
run satisfactorily.

To run a program, use the RUN command:

        $ run pgdemo1
        $ run pgdemo2
        ...
        $ run cpgdemo    ! optional component
        $ run pgmdemo    ! optional component

All the demonstration programs prompt for a device name and type. Type a
question mark ? to see a list of the available device types and verify that
PGPLOT has been configured properly.

Points to check for: the PGPLOT program correctly reads the font file and
displays superscripts, subscripts and special characters (pgdemo2); the
PGPLOT program can read the color database (pgdemo10); on interactive
devices, the cursor works correctly (pgdemo5, pgdemo6).

9. Install the documentation files

Unlike the UNIX installation procedure, the VMS installation procedure does
not generate documentation. A list of subroutine synopses is available in a
variety of formats by anonymous ftp from
ftp://astro.caltech.edu/pub/pgplot/DOC/:

   * pgplot.doc (plain ASCII file)
   * pgplot.hlp (VMS help format)
   * pgplot.html (HTML [WWW] format)
   * pgplot.ps (PostScript)

The help file can be installed in a VMS help library with a DCL command like
the following:

        $ library/insert/help pgplot.hlb pgplot.hlp

----------------------------------------------------------------------------
PGPLOT
Tim Pearson, California Institute of Technology, tjp@astro.caltech.edu
Copyright © 1997 California Institute of Technology