README March 1, 1996 revised December 11, 1996 revised March 6, 1998 revised June 29, 1998 LIB lib - Version 3.0 1996/03/01 Version 3.1 1996/12/11 Version 3.2 1998/03/06, 1998/06/29 libraries for: aide and wdm graphics statistics hspf utility data ananlysis utility programs: wdimex wdmrx lib3.2.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 lib3.2.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.2 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., Jr., and Johanson, R.C., 1997, Hydrological Simulation Program--Fortran, User's manual for version 11: U.S. Environmental Protection Agency, National Exposure Research Laboratory, Athens, Ga., EPA/600/R-97/080, 755 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.2/doc direcory. See the file lib3.2/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.2 are contained in the files lib3.2.______.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.2 will be created (or overwritten) when the files are extracted from the tar tape. If the lib3.2 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.2.______.tar.gz /usr/opt/wrdapp If the tar file is not already in the directory where you want lib3.2 installed, move it there. cd /usr/opt/wrdapp Change to the directory where the tar file is located. gunzip lib3.2.______.tar.gz Uncompress the file. tar xf lib3.2.______.tar Extract the files. This creates the following directory structure: lib3.2 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.2.source.tar.gz file; they are created during compilation. b) Source code is included only with the lib3.2.source.tar.gz distribution. c) It is recommended that no user files be kept in the lib3.2 directory structure. If you plan to put files in the lib3.2 directory structure, do so only by creating subdirectories under lib3.2. 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.2.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.2 files may need to be modified (see the file lib3.2/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.2/src, run the make: cd lib3.2/src make The lib3.2/src/Makefile will: a. Create the directories lib3.2/lib, lib3.2/lib_data, and lib3.2/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.2/lib. The programs will be placed in lib3.2/bin. c. Run the wdimex.sh script in lib3.2/msg to build the message files (message.wdm and hspfmsg.wdm). The message files will be placed in lib3.2/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.2/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.2/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.2/lib and BINDIR equals lib3.2/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.2 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.2/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