MPLOT98v1.3: RELEASE NOTES AND INSTALLATION GUIDE

Introduction:

The mplot and umplot plotting programs are X11 applications which allow the user to browse and visualise 2-D sections of OCCAM archive data. Slices can be orientated along any of the model axes. Features include: zooming and panning, choice of colour scales, user-controllable limits. PostScript output and the ability to combine two slices together either as a difference or a vector field. Images are displayed in a rectangular window with an approximately 3 to 1 ratio.

This guide is intended for people installing mplot98 (version1.3) and umplot98 (version 1.3) or later versions. Several improvements to the original software have now been made and an updated user manual is now available and can be downloaded with the source code for the plotting program. If the user has little or no prior knowledge of UNIX system, then they are advised to seek the help of a UNIX administrator.

(Please note: code for the umplot98 program is automatically provided in the following packages. In order to compile, install and use umplot98, the user must have a licence for UNIRAS).

The following software is currently available:

An on-line user manual can be accessed at the following address

http://www.noc.soton.ac.uk/JRD/OCCAM/man/mplot98

An example data set can be obtained from the following site:

(still to be confirmed)

Please keep checking this page for the availability of the data. To obtain a full list of data available via anonymous ftp.

If you are installing the software for the first time please notify the acc@soc.soton.ac.uk

Installation Notes:

The OCCAM plotting programs have been tested on the following platforms

Sun4 (SunOS4.1.1)
Solaris (solaris 2.5)
SGI and SGI-Indy (IRIX5.2, IRIX5.3, IRIX646.2)
DEC-ALPHA (OSF1v4.0)

If you wish to compile the software on any other machines, then you will have to edit the configure script provided with the software to meet your demands.

The code is written mainly in ansi C, but old code fragments still remain in K&R C. The compiler used must be able to compile both kinds. We suggest using the gcc compiler for SunOs since the native cc compiler will not compile the code.

Version have been compiled using HDF3.3r1. Only the those machines running on the IRIX platforms have been tested with HDF4.0 and later versions.

You can obtain the latest version of HDF from

http://hdf.ncsa.uiuc.edu

Installing the software:

The mplot98v1.3 and later versions are supplied in a single compressed tar file.

Installing the files:

1. Select a location where you want the support files to be installed. Change to this directory. This will be the root directory where the file configuration will take place. This will be regarded as the top_level directory.

2. The *.tar.Z file holds all the source code, include directories and source code for the executable. To install these on your machine set the environment variable SOURCE_LOCATION to the directory where the tar.Z file was downloaded and now install the files

% zcat $SOURCE_LOCATION/*.tar.Z | tar xvf -

If you do a ls in the current directory you should now have a new directory called MPLOTv1.3 (please note this will vary depending on the version number and the plotting program you have downloaded).

Change to this directory and :

%ls -1F

You should now have the following list in the current directory

README.INSTALL
README.INSTALL.UNIRAS
VERSION
bin/
colour/
occinstall_m*
occinstall_u
edit_paths_template
include/
src/

General Configuration and Installation Notes:

The occinstall_m and occinstall_u scripts provided with the code do not guess the configuration of the machine on which you are installing the software. You will be prompted when running the script to select the type of machine architecture you are installing the software on. The script for installing the executables are in the current directory (i.e $top_level/MPLOTv1.3/occinstall_m and $top_level/MPLOTv1.3/occinstall_u ). The scripts are currently able to build the makefiles for installation on the the following platforms

SGI
SUN
SOLARIS
DEC-ALPHA

If you wish to compile the executable for other platforms then you may have to edit the occinstall* scripts. The occinstall* scripts performs two operations a) builds a makefile to compile the executable for the current machine architecture, which is then placed in the ./src directory ( ref Running occinstall_m and Running occinstall_u ) and b) creates a c-shell script - setup_mplot, which sets the environment variables COLOUR_DIR and DATA_DIRPATH and the paths to where the executables have been installed and any other library paths required by the executable and then placed in a user-defined directory. The user may source this file to setup the paths to the executable and support files or else use the file to adapt their .login or .cshrc file if using the plotting program regularly. (Setting environment variables)

Running occinstall_m:

The occinstall_m script from the current directory i.e $top_level/$version.

The occinstall_m script will prompt you for the following information

Enter top level directory where the software installed:

The script will now take the version number of the software from the ./VERSION file to create the full directory path were the installation has taken place. If this directory path does not exist an error message will be displayed and the configure script terminated.

It will then prompt the user to select one of the machine architectures on which the executable is to be installed.

Enter choice of machine architecture
(1) IRIX
(2) SunOS
(3) Solaris
(4) Dec Alpha

The script will now prompt the user for the location of the HDF include and libary files. Please note that only versions compiled for IRIX platforms have been tested with versions of HDF4.0 and later

Enter location of HDF include files
>
Enter location of HDF library files
>

Each of these directories will be checked to see if they exist and the occinstall_m script will try to guess which version of HDF is been used in order to set up the correct libraries to be used when compiling the executable. If the script cannot ascertain this correctly then the configure script will be terminated.

Once this information has been provided, the script will now automatically generate a makefile for compiling the executable and place this in the ./src directory. Since the makefile is dependant on some dynamic links to libraries, some assumptions have been made about the platforms you are running on. Please refer to the section on platform-specific-notes.

When the makefile has been created, the occinstall_m script will now generate a c-shell script - setup_mplot. The script setups up the path to the executable and other library paths required for the specific machine architecture. The script can be placed in a directory ($dest_dir) of the users own choice i.e /users/<user_name>/bin. It is recommended that this script is placed in a different directory from the current directory and that the directory is in the users PATH variable.

%Please enter destination directory for setup_occam script

If a copy of setup_occam already exists in the directory given, the user shall be prompted whether to overwrite the existing file.

 %echo setup_mplot ':File already exists in ' $dest_dir
 %echo 'Do you wish to overwrite'

If this is the first time installing the software, or else you wish to overwrite the existing file, the setup_mplot script will be copied to $dest_dir.

Running occinstall_u:

The occinstall_u script the compiles the software with different flags in order to build in the UNIRAS extension to the MPLOT program. The user must have a licence to run UNIRAS on their machines and must also have the paths locating the bin, include and lib directories already set in their $PATH variable.

The occinstall_u script creates a Makefile in the .src directory ( it will overwrite any existing Makefile).

The setup_umplot script will also be generated and should be placed in a directory whose path is in the PATH variable. To create the executable, refer to the section Compiling.

Changing default values

If you wish to change any of the default variables or reset any of the options edit ./src/Makefile. This can also be done if running on a particular operating system. If you are running after a previous make then run make clean before running another make or configure.

Platform-Specific-Notes

IRIX platforms

Compilaton for this machine architecture requires a dynamic link to the libraries for libmalloc.a and libma .a in order to compile the executable correctly. A default setting for these libraries has been set to /usr/lib. If the configure script is unable to find the this directory , then the configure script will request the name of a directory where the libraries can be found on the users system.

If these libraries cannot be found then the configure script will be terminated.

Umplot Requirements:

Compilation of the umplot executable uses "unilink" to link together the object files to the uniras libraries. This requires the uniras library path to be setup before running the Makefile. The script does NOT setup these paths. If you do not know if these paths have been setup correctly in your working environment then you are asked to seek the help of your UNIX administrator.

SunOS/Solaris

The Sun systems run using the OpenWindows systems. In order to compile an executable for the following platforms the default location for the X11 directory is set to the default path /usr/openwin/include. This path may vary between different operating systems. If the configure script cannot find the X11 directory in the above path, if will prompt the user to input the pathname for their particular system and check until the correct path has been entered.

Uniras option:SunOS

Uniras has been tested on the above platfrom using 6v3a, which may also requires the Motif window manager library libXt.a and libXm.a. Both paths to the uniras and motif libraries should be setup in your .login or .cshrc file before trying to compile the executable. If you have trouble compiling the executable, then you may have to edit some of the paths in the Makefile or else ask the help of a UNIX administrator. The $uniras_path variable is the path which is required for the location uniras library -llibuni.a , this may vary depending on the system setup and the version of uniras which is currently installed. We advise you to try compiling the program using unilink, problems on our own systems under SunOS failed so we adopted the following code. If your system allows then use the unilink option. Create the makefile following the normal procedure and then adapt it to your own needs.

The following commands are used to compile the exectuable on this platform

HDF_PATH = 
UNILIB = directory of uniras libraries. No default setting
XLIBPATH = -L/usr/lib -L/$uniras_path/lib 
HDFLIB = -L$HDF_PATH/lib

$(EXEC):$(OBJS)
 gcc -s  -o $(EXEC) $(OBJS) -L$(UNILIB) -L/usr/lib -L$(HDF_LIB)\
 -lsunwindow -lsuntool -lpixrect -lnetcdf -ldf -lX11 -lm -luni -lXm \
 -lXt -lF77 -lm -ldl -lc -ldum
 rm $@.o
 /bin/mv $(EXEC) $(U_EXEC)

The user may have to edit the Makefile for their own use, setting default

paths where asked to and then editing when created.

Uniras Option:Solaris

Testing carried out of Solaris machines used version 6v4a of uniras which require motif. Motif paths therefore need to be setup before the executable can be compiled. (Version 1.2.2 of IXI OSF/Motif was used in this case).

GRAPHICS_INC: Directory path for source include files
HDF_ROOT: Root directory of HDF source files
HDFINC = $HDF_ROOT/include

OBJS  = mplot.o
XLIBS = -lsunwindow -lsuntool -lpixrect -lX11 -lm -lnsl
$(EXEC):$(OBJS)
     unilink -exec $(UEXEC) $@.o -L$(HDFLIB) $(LIBPATH) $(LIBS) $(XLIBS)

$(OBJS):
     gcc -I$(HDFINC) -I$(GRAPHICS_INC) $(CFLAGS) -c mplot.c


DEC-ALPHA

Uniras Option: Compiled using version v6vb uniras. Please be warned. The program will compile for DEC-ALPHA's but has not successfully run.

To compile the umplot version for DEC-ALPHA, the following :

CC = cc -oldc -Olimit 700
EXEC = mplot
UEXEC = umplot98
OBJS = mplot.o
SRC  = mplot.c
HDF_PATH = root directory for location of HDF source code
HDFLIB = HDF_PATH/lib
LIBPATH = -L$(HDFLIB)
XLIBPATH = 
LIBS = -lnetcdf -ldf -lX11 -lXm (note:HDF libraries depend on HDF version)

$(EXEC):$(OBJS)
       unilink -exec $(U_EXEC) $(OBJS) $(LIBPATH) $(LIBS)
       /bin/rm $(OBJS)

c.o:
      $(CC) $(CFLAGS) -c -O $(SRC)

Compiling the Software

To compile the executable

%cd src 

If previous compilations have been made and old object files or exectubles exist in the current directory then type

make clean

This will clean the current directory.

To make the executable and install in $installdir then type:

make install

The executable should now be installed in $top_level/bin. If you are compiling multiple versions for different operating systems, then it will be necessary to move the executable to another directory specific to that architecture between successive compilations.

Setting Environment Variables

The setup_mplot and setup_umplot c-shell scripts , created from the occinstall scripts, sets the environment variables required by the executable. COLOUR_DIR - location of the directory which contains the colour files provided with the software and the DATA_DIRPATH which is the location of a directory where data files are kept.

The setup* scripts also sets up the paths to where the executable has been installed on the system. If the user at any time changes the location of the executable, for example, when doing consecutive compilations of the program for different machine architectures, then the user should edit the MPLOT_BIN environment variable to the new path.

If the user will be running the program a number of times, then the following line should be added to the .login file

%source $dest_dir/setup_mplot
and/or
%source $dest_dir/setup_umplot

If using the program only occasionally, then the user can run

%source $dest_dir/setup_mplot

before running the program.

Alternatively the lines of code from the setup_mplot/setup_umplot scripts can be added to the users .login or .cshrc file. (You may require the help of a UNIX administrator to do this).