README.TXT LIBANNE A set of libraries for use with hydrologic applications Version 4.0 2002/02/25 libraries for: aide and wdm graphics statistics utility data analysis utility programs: wdimex wdmrx IMPORTANT NOTE: If you have n-day data sets that were created using the N-day option in version 3.2 of SWSTAT, you will need to run WDMRX to correct a problem with the SEADBG and SEADND attributes. WDMRX is distributed with ANNIE (http://water.usgs.gov/software/annie.html) and SWSTAT (http://water.usgs.gov/software/swstat.html) as well as LIBANNE. Instructions for installation and use are provided below. After installation, see libanne.txt in the doc subdirectory for summary information on LIBANNE. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DISTRIBUTION FILE C. DOCUMENTATION D. INSTALLING o Installing LIBANNE o LIBANNE directory structure E. COMPILING (optional) F. RUNNING THE SOFTWARE G. UNINSTALLING H. CONTACTS A. SYSTEM REQUIREMENTS To install LIBANNE, the following are necessary: - Pentium-class PC - Windows 9x/Me, Windows NT 4.0, or Windows 2000 - up to 8.4 megabytes of free disk space B. DISTRIBUTION FILE The following distribution file (containing the software and information files) is currently available. libanne4_0.exe - Compiled using Lahey Fortran 90, includes source C. DOCUMENTATION The libanne libraries are used in various combinations by a number of water-resources applications, including ANNIE, IOWDM, SWSTAT, PEAKFQ, GLSNET, DR3M, HSPEXP, HSPF, HYSEP, and PRMS. 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, table, text, vector, space-time, and descriptive attribute data types are currently supported in the WDM file format. (Requires wdm.lib, adwdm.lib, and util.lib.) The ANNIE Interactive Development Environment (AIDE) library provides a set of routines for building interactive, character-based 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 aide.lib, adwdm.lib, and util.lib.) The graphics (GRAPH) library contains a set of routines for drawing axes, curves, and symbols. Requires a user-supplied Graphical Kernel System (GKS) library. (Requires graph.lib and util.lib.) Computer generated documentation for the util.lib, graph.lib, wdm.lib, aide.lib, and adwdm.lib libraries is included in the doc subdirectory. See these files: utillib.txt general utility routines graphlib.txt graphics routines wdmlib.txt watershed data management routines aidelib.txt aide user interface adwdmlib.txt routines shared by wdm and aide libraries 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. 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. See http://water.usgs.gov/software/ordering_documentation.html for information on ordering printed copies of USGS publications. For information on ordering printed copies of EPA publications, see National Technical Information Service 5285 Port Royal Road Springfield VA 22161 electronic mail: orders@ntis.fedworld.gov Phone: 1-800-553-NTIS (6847) or (703) 605-6000 Fax: (703) 605-6900 web: http://www.ntis.gov/ D. INSTALLING Installing LIBANNE ------------------ Double-click libanne4_0.exe to execute the installation program. Follow the directions on the screen. By default, the software is installed in the directory C:\Program Files\USGS\libanne4.0. This is the recommended installation directory, but you may use other directories or disk drives. Note that program components not installed initially can be installed later, and that any components damaged by, for example, being inadvertently overwritten, can be quickly reinstalled by double-clicking libanne4_0.exe--a maintenance version of the installation program will be executed. LIBANNE directory structure --------------------------- The following directory structure will be created (the contents of each directory are shown to the right): libanne4.0 files NOTICE.TXT, RELEASE.TXT, and this README.TXT `-----bin compiled utility programs: WDIMEX, WDMRX `-----bin_data data file req'd. by utility prog.s during execution INTERACTER character sets for use with graph.lib `-----doc documentation files (see file Contents.txt) `-----src Makefile `-----adwdm --+ `-----aide | `-----ann | `-----awstat +-- for each library and program: `-----graph | `-----stats | 1. makefile `-----util | `-----waide | 2. source code `-----wdimex | `-----wdm | `-----wdmrx --+ `-----msg wdimex.bat batch file to build message file `-----adwdm --+ `-----aide | `-----ann +-- text versions of the message file `-----awstat | groups for the indicated libraries `-----waide --+ `-----lib compiled libraries: adwdm.lib, aide.lib, ann.lib, awstat.lib, graph.lib, stats.lib, util.lib, waide.lib, wdm.lib `-----lib_data unformatted, binary direct access message file: message.wdm `-----user batch files for running utility programs Notes: a) The src and msg subdirectories are not installed in the Typical or Compact installations, but can be installed by choosing the Custom installation and selecting the Source Code component. b) The Compact installation will install only the bin, bin_data, lib, lib_data, and user subdirectories. c) It is recommended that no user files be kept in the library directory structure. If you plan to put files in the library directory structure, do so only by creating subdirectories. E. COMPILING (optional) The source code is provided so that users can compile the libraries for themselves. Little or no support can be provided for users generating their own versions of the software. In general, to compile a new version of the software, you will need: a) a Fortran compiler (77 or later), b) familiarity with the compiler and the operating system under which the compiler runs (i.e., DOS or Windows), and c) while not required for compiling the libraries, the INTERACTER library from Interactive Software Services Ltd. (http://www.demon.co.uk/issltd/) is required to use the graph.lib library. INTERACTER is not a GKS library, but it is utilized by the DOS version of the libanne graphics system through the use of code that substitutes appropriate INTERACTER subroutine calls for GKS subroutine calls: gksint.for. To use graph.lib with a GKS library, graph.lib must be rebuilt so as to omit gksint.obj. Other source-code changes may also be required. Note that under Windows NT/2000 the libraries must be compiled as DOS libraries and the utility programs must be compiled as DOS executables (as opposed to Windows console-mode executables). Subroutines within util.lib require the ANSI.SYS device driver, but ANSI.SYS is only supported for DOS applications and not for Windows applications under Windows NT/2000. The Opus Makefiles used to compile the libraries and executables, using the Lahey Fortran 90 compiler and the INTERACTER graphics library, are provided as an example. Lahey previously distributed the Opus make program with its compilers, but has since substituted the simpler automake program. The syntax of the Makefiles used with Opus make is very similar to that of UNIX make and can be adapted for use with other make programs. There will likely be further changes needed to compile using a different compiler. The versions.txt file found in the doc subdirectory identifies items that may need to be changed. To generate the libraries, utility executables, and message file, do the following: 1. The values for the indicated variables in the following files may need to be modified (see versions.txt in the doc subdirectory for more details): variables that may need to be modified -------------------------------------- compiler file name version lib archiver flags name --------------------- ---------- ------------ ------------ src\Makefile SeqVrsn util\makefile ObjVrsn AR FFLAGS FC adwdm\makefile ObjVrsn AR FFLAGS FC fmsgwd.inc WDNAME wdm\makefile AR FFLAGS FC aide\makefile ObjVrsn AR FFLAGS FC fmsgwd.inc WDNAME awstat\makefile AR FFLAGS FC graph\makefile ObjVrsn AR FFLAGS FC stats\makefile AR FFLAGS FC waide\makefile AR FFLAGS FC ann\makefile AR FFLAGS FC wdimex\makefile AR FFLAGS FC LDFLAGS wdmrx\makefile AR FFLAGS FC LDFLAGS fmsgwd.inc WDNAME wdmrx.for RECL msg\wdimex.bat Vers 2. Run the make program in the src directory to compile the source, build the libraries and utility programs, and create the message file: cd libanne4.0\src make [ldir=lib_path] [bdir=bin_path] where lib_path and bin_path are the pathnames of directories in which copies of the libraries and utility programs, respectively, can optionally be placed. Running make will: a. create the libanne subdirectories lib, bin, and lib_data, if they do not already exist, b. run make in each of the subdirectories under src to compile the source code and build the libraries and utility programs, placing the libraries in lib and the executables in bin, c. run the wdimex.bat batch file in msg to build the message file and place it in lib_data. Note: This MAY take a while. F. RUNNING THE SOFTWARE If the option to modify the PATH environment variable was chosen during installation, the LIBANNE utility programs, WDIMEX and WDMRX, can be run in an MS-DOS Command Prompt window from any directory by typing "wdimex" and "wdmrx", respectively. If the option to modify the PATH environment variable was not chosen during installation, the full path name of the program must be typed, as in, for example, "c:\program files\usgs\libanne4.0\bin\wdmrx" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run the utility programs by selecting the shortcuts from the Start menu. The LIBANNE shortcuts are found under Programs, in the Program Folder specified during installation (default: USGS). The shortcuts will run the utility programs from the user subdirectory. Therefore, if an input file name is specified with no directory path preceding the name, the input file will be expected to be found in the user subdirectory. Likewise, if an output file name is specified without a directory path preceding the name, the output file will be placed in the user subdirectory. G. UNINSTALLING To uninstall LIBANNE, double-click Add/Remove Programs in the Control Panel, select LIBANNE 4.0, and click the Add/Remove button. Any user files in the LIBANNE installation directory--such as those created in the user subdirectory--will be left behind intact. H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov