README                                                   March 1, 1996
                                             revised December 11, 1996


                               LIB

                      lib - Version 3.0  1996/03/01
                            Version 3.1  1996/12/11

                        libraries for:   aide and wdm
                                         graphics
                                         statistics
                                         hspf
                                         utility
                                         data ananlysis
                      utility programs:  wdimex
                                         wdmrx


   lib3.1.DGUX.tar.gz   - Distribution prepared on a Data General
                          AViiON under DG/UX 5.4
   lib3.1.source.tar.gz - Distribution that includes the source code
                          but no compiled software

                          TABLE OF CONTENTS

                          A. DESCRIPTION
                          B. DOCUMENTATION
                          C. EXTRACTING FILES
                          D  COMPILING
                          E. INSTALLING
                          F. CONTACTS


A. DESCRIPTION

The lib3.1 libraries are used in various combinations by a number of
water-resources applications, including ANNIE, IOWDM, SWSTAT, PEAKFQ,
GLSNET, DR3M, HSPEXP, HSPF, PRMS, and METCMP.

The ANNIE Interactive Development Environment (AIDE) library provides a
set of routines for building interactive interfaces.  The library contains
tools to build a user interface that provides a consistent methodology for
displaying text and for querying the user for (1) menus, (2) forms, (3) tables,
and (4) file names.  (Requires aidelib, adwdmlib, and utillib.)

The Watershed Data Management (WDM) library provides a mechanism for managing
in a single storage file the kinds of data needed to perform water-resources
investigations.  Time-series, tables, text, vectors, space-time, and
descriptive attribute data types are currently  supported in the WDM file
format.  (Requires wdmlib, adwdmlib, and utillib.)

The graphics (GRAPH) library contains a set of routines for drawing axis,
curves, and symbols.  Requires a GKS library.  (Requires graphlib and
utillib.)

The Hydrological Simulation Program--Fortran (HSPF) library contains
the parts of HSPF that are shared by other programs, including HSPF,
HSPEXP, and GENSCN.  (Requires hspflib, wdmlib, adwdmlib, utillib,
and hspnodsslib.a)


B. DOCUMENTATION

Kittle, J.L., Jr., Hummel, P.R., and Imhoff, J.C., 1989, ANNIE-IDE, A
   system for developing interactive user interfaces for environmental
   models (Programmers Guide):  Environmental  Research Laboratory,
   U.S Environmental Protection Agency, Athens, Ga., EPA/600/3-89/034,
   166 p.

Lumb, A.M., Carsel, R.F., and Kittle, J.L., Jr., 1988, Data management
   for water-quality modeling development and use:  Proceedings of the
   International Conference on Interactive Information and Processing
   Systems for Meteorology, Oceanography, and Hydrology.

Bicknell, B.R., Imhoff, J.C., Kittle, J.L., Jr., Donigian, A.S., and
   Johanson, R.C., 1993, Hydrological Simulation Program--Fortran,
   Users Manual for Release 10:  EPA-600/R-93/174, Environmental
   Research Laboratory, U.S Environmental Protection Agency, Athens, Ga.,
   660 p.

Kittle, J.L., Jr., Flynn, K.M., Hummel, P.R., and Lumb, A.M.,
   Programmers manual for the watershed data management (wdm) system,
   1991, written communication, 190 p.

Computer generated documentation for selected libraries is included
   in the lib3.1/doc direcory.  See the file lib3.1/doc/Contents for
   a listing of the available library documentation.


C. EXTRACTING FILES

Compressed tar files are used to distribute pre-compiled versions of the
software and the source code.  All of the files needed to install lib3.1
are contained in the files lib3.1.______.tar.gz (where ______ is a string
indicating the file contains either the source code or a pre-compiled
version of the library for the indicated operating system).  The source
version of the tar file contains the source code and all other files 
needed to compile and install the software on a UNIX-based computer.  The
directory lib3.1 will be created (or overwritten) when the files are
extracted from the tar tape.  If the lib3.1 directory already exists, you
may want to delete or rename it before extracting the files.  The following
are the steps to extract the software from a distribution file.

  Steps in extracting files                explanation
  ---------------------------------------  -----------------------------------
  mv lib3.1.______.tar.gz /usr/opt/wrdapp  If the tar file is not already in
                                           the directory where you want lib3.1
                                           installed, move it there.

  cd /usr/opt/wrdapp                       Change to the directory where the
                                           tar file is located.

  gunzip lib3.1.______.tar.gz              Uncompress the file.

  tar xf lib3.1.______.tar                 Extract the files.

This creates the following directory structure:

   lib3.1                    release notes and this README file
     `-----doc               documentation files (see file Contents)
     `-----msg               wdimex.sh script to build message files
             `-----adwdm     --+
             `-----aide        |
             `-----ann         |
             `-----awstat      +-- text versions of the message file
             `-----hspf        |   groups for the indicated libraries
             `-----newaqt      |
             `-----waide     --+
     `-----src               Makefile
             `-----adwdm     --+
             `-----aide        |
             `-----ann         |
             `-----awstat      +-- for each library and program:
             `-----graph       |
             `-----hspf        |   1.  makefile
             `-----hspnodss    |
             `-----newaqt      |   2.  source code, if the source tar
             `-----stats       |       file is untarred
             `-----util        |
             `-----waide       |
             `-----wdimex      |
             `-----wdm         |
             `-----wdmrx     --+
     `-----lib               compiled libraries
     `-----lib_data          unformatted, binary direct access message files
     `-----bin               compiled utility programs

Notes:  a) The lib, lib_data, and bin subdirectories are not included
           with the lib3.1.source.tar.gz file; they are created during
           compilation.
        b) Source code is included only with the lib3.1.sourc.tar.gz
           distribution.
        c) It is recommended that no user files be kept in the lib3.1
           directory structure.  If you plan to put files in the lib3.1
           directory structure, do so only by creating subdirectories
           under lib3.1.
        d) The software is configured for installation under the
           directory /usr/opt/wrdapp.  The wrdapp directory may be
           a separate file system mounted at /usr/opt/wrdapp.  If
           you choose to install the library elsewhere, you will need
           to retrieve the source version of the tar file and compile
           the software.


D. COMPILING

If you have retrieved a pre-compiled distribution of the software, skip to
the Installing section below.  If a compiled version of the software is not
available for your operating system, or if you want to build the libraries
yourself, follow the instructions in this section.

The source code is provided in the lib3.1.source.tar.gz distribution so
that users can generate the libraries themselves.  Little or no support
can be provided for users generating their own versions of the software.
In general, the requirements are ANSI-compliant Fortran 77 and C compilers
and a minimum level of knowledge of the compilers and the UNIX operating
system.  A Graphical Kernel System (GKS) library will be required to
use the graphics library.  As provided, the make files, source code, and
text versions of the message files are set up for use on Data General
AViiON workstations running the DG/UX operating system.  To generate the
library archives, utility executables, and message files, do the following:

1.  The indicated variables in the following lib3.1 files may need to be
    modified (see the file lib3.1/doc/versions.doc for more details):

                              variables that may need to be modified
                           --------------------------------------------
    file name              version   lib archive  compiler flags & name
    ---------------------  -------  ------------  ---------------------
    src/Makefile           SeqVrsn
        util/makefile      ObjVrsn  SymTbl ArOpt  FFLAGS F77  CFLAGS CC
        adwdm/makefile     ObjVrsn  SymTbl ArOpt  FFLAGS F77
              fmsgwd.inc   WDNAME
        wdm/makefile                SymTbl ArOpt  FFLAGS F77
        aide/makefile      ObjVrsn  SymTbl ArOpt  FFLAGS F77
             fmsgwd.inc    WDNAME
        awstat/makefile             SymTbl ArOpt  FFLAGS F77
        graph/makefile     ObjVrsn  SymTbl ArOpt  FFLAGS F77
        stats/makefile              SymTbl ArOpt  FFLAGS F77
        waide/makefile              SymTbl ArOpt  FFLAGS F77
        ann/makefile                SymTbl ArOpt  FFLAGS F77
        hspf/makefile               SymTbl ArOpt  FFLAGS F77
        newaqt/makefile             SymTbl ArOpt  FFLAGS F77
        hspnodss/makefile           SymTbl ArOpt  FFLAGS F77
        wdimex/makefile             SymTbl ArOpt  FFLAGS F77
        wdmrx/makefile              SymTbl ArOpt  FFLAGS F77
              wdmrx.f      RECL

2.  Run the Makefile program in the src directory to compile the source,
    build the libraries and utility programs, and create the message files.
    In the directory lib3.1/src, run the make:

        cd lib3.1/src
        make

    The lib3.1/src/Makefile will:

        a.  Create the directories lib3.1/lib, lib3.1/lib_data, and
            lib3.1/bin if they do not already exist.

        b.  Run each of the makefile programs in the subdirectories
            under src to compile the source code and build the
            libraries and utility programs.  The libraries will be
            placed in the directory lib3.1/lib.  The programs will
            be placed in lib3.1/bin.

        c.  Run the wdimex.sh script in lib3.1/msg to build the
            message files (message.wdm and hspfmsg.wdm).  The message
            files will be placed in lib3.1/lib_data.

    Note:  This WILL take a while.


E. INSTALLING

To make the libraries and utility programs easy to use, they should be
installed in directories included in the user's library and executable
search paths, respectively.  The Makefile in lib3.1/src contains the
instructions to automatically link the libraries and programs to the
specified directories.  Use the following two commands to do this:

    cd lib3.1/src
    make install [LIBDIR=lib_path] [BINDIR=bin_path]

where lib_path and bin_path are the names of directories in the user's
path.  If LIBDIR and BINDIR are specified, the libraries and utility
programs are linked to the specified directories, respectively.  By
default, LIBDIR equals lib3.1/lib and BINDIR equals lib3.1/bin.

Examples of values for lib_path and bin_path are:

    make install LIBDIR=/usr/local/lib BINDIR=/usr/opt/bin
    make install LIBDIR=$HOME/lib BINDIR=$HOME/bin

Notes:  a) Brackets "[xxx]" are used to indicate optional arguments
           to commands.
        b) The installer must have sufficient access rights to the
           LIBDIR and BINDIR directories to create links to the
           libraries and utility programs and to delete any existing
           lib3.1 libraries or utility programs (see list below).
        c) By setting LIBDIR and BINDIR to directories in the users'
           search path, the libraries can be conveniently loaded from
           any directory on your computer and the programs can be easily
           executed from any directory.

After installation, the following libraries, utility programs, and message
files should be available to the users:

  directory        available files
  ---------------  --------------------------------------------------
  LIBDIR           adwdmlib.a  aidelib.a  annlib.a       awstatlib.a
                   graphlib.a  hspflib.a  hspnodsslib.a  newaqtlib.a
                   statslib.a  utillib.a  waidelib.a     wdmlib.a
  BINDIR           wdimex      wdmrx
  lib3.1/lib_data  message.wdm hspfmsg.wdm


F. CONTACTS

Inquiries about this software distribution should be directed to:

  U.S. Geological Survey
  Hydrologic Analysis Software Support Team
  Kathleen M. Flynn                           e-mail:  h2osoft@usgs.gov
  437 National Center                         phone:   703-648-5313
  Reston, VA  22092                           fax:     703-648-5722
