README.TXT IOWDM Input and Output to a Watershed Data Management File Version 4.1 2002/02/25 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). Instructions for installation, execution, and testing are provided below. After installation, see iowdm.txt in the doc subdirectory for summary information on IOWDM. 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 IOWDM o IOWDM directory structure E. COMPILING (optional) F. RUNNING THE SOFTWARE o Out of environment space error G. TESTING H. UNINSTALLING I. CONTACTS A. SYSTEM REQUIREMENTS To install and run IOWDM, the following are necessary: - Pentium-class PC - Windows 9x/Me, Windows NT 4.0, Windows 2000, or Windows XP - up to 2.9 megabytes of free disk space - 2.1 megabytes of free memory - on Windows 9x/Me machines, MS-DOS Command Prompt window memory settings as described below A memory protection fault error can occur on Windows 9x/Me machines if the memory settings of MS-DOS Command Prompt windows are not set as follows: After opening an MS-DOS Command Prompt window, click the icon in the upper left corner of the window and select the Properties menu item. Select the Memory tab and modify the fields to set everything to "Auto", but change "Expanded (EMS) memory" to "none" and enter 65535 (the maximum allowed value) in the "MS-DOS protected-mode (DPMI) memory" input field. B. DISTRIBUTION FILE The following distribution file (containing the software, test data sets, and information files) is currently available. iowdm4_1.exe - Compiled using Lahey Fortran 90, includes source C. DOCUMENTATION Lumb, A.M., and Kittle, J.L., Jr., and Flynn, K.M., 1990, Users manual for ANNIE, a computer program for interactive hydrologic analyses and data management: U.S. Geological Survey Water-Resources Investigations Report 89-4080, 236 p. The IOWDM program was originally documented in the above report. Updated documentation for the current version of the iowdm program is not available. Descriptions of the supported data formats and examples of program sessions can be found in the doc subdirectory, see the file Contents.txt. The ANNIE manual (listed below) may be useful for understanding how the user interface and the wdm file work. Flynn, K.M., Hummel, P.R., Lumb, A.M., and Kittle, J.L., Jr., 1995, User's manual for ANNIE, version 2, a computer program for interactive hydrologic data management: U.S. Geological Survey Water-Resources Investigations Report 95-4085, 211 p. This document is available in electronic format. A Portable Document Format (PDF) version is included in the doc subdirectory of the ANNIE program distribution. This and other formats can also be found at http://water.usgs.gov/software/annie.html. See http://water.usgs.gov/software/ordering_documentation.html for information on ordering printed copies of USGS publications. D. INSTALLING Installing IOWDM ---------------- Follow the steps below to install IOWDM: 1. If a previous version of IOWDM is already installed, remove it. If you previously installed IOWDM 4.0, double-click Add/Remove Programs in the Control Panel, select IOWDM 4.0, and click the Add/Remove button. Any user files in the IOWDM installation directory--such as those created in the test or user subdirectories--will be left behind intact. Move any such user files that need to be retained to another directory and delete the old iowdm4.0 installation directory. -- OR -- If you previously installed an earlier version of IOWDM, move to another location any data files that you happened to store in the IOWDM installation directory, then: a) Delete the iowdmX.X directory and its contents, where X.X is the version number of the previously-installed version. b) If you modified the PATH environment variable to make the previous version of IOWDM easily accessible from any directory, remove the iowdmX.X\bin directory from the PATH environment variable: (1) On Windows 9x machines, edit C:\AUTOEXEC.BAT to remove the iowdmX.X\bin directory from the "set PATH=" command. Reboot your system after modifying AUTOEXEC.BAT. (2) On Windows Me machines, select Run from the Start menu, enter "msconfig", and click OK. Select the Environment tab, select the PATH variable, and click the Edit button. Remove the iowdmX.X\bin directory from the value of PATH and click OK. (3) On Windows NT/2000 machines, double-click System in the Control Panel, select the Environment tab, and modify the value for Path to remove the iowdmX.X\bin directory. Rebooting is not necessary, but any existing MS-DOS Command Prompt windows should be closed and reopened. 2. Double-click iowdm4_1.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\iowdm4.1. 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 iowdm4_1.exe--a maintenance version of the installation program will be executed. IOWDM directory structure ------------------------- The following directory structure will be created (the contents of each directory are shown to the right): iowdm4.1 files NOTICE.TXT, RELEASE.TXT, and this README.TXT `-----bin compiled executable `-----bin_data data files required during execution `-----doc documentation files (see file Contents.txt) `-----src Makefile and source code `-----msg files for building message file `-----test files for running verification tests `-----data standard data sets used in verification tests `-----user batch file for running executable 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, and user subdirectories. c) It is recommended that any user files kept in the IOWDM directory structure be placed in the user subdirectory only. d) To compile a new version of the software, you will also need: (1) libraries and other data files from the libanne library distribution (version 4.0, or later, available from http://water.usgs.gov/software/libanne.html), and (2) a Fortran compiler (77 or later). E. COMPILING (optional) The source code is provided so that users can generate the executable 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) libraries and other data files from the libanne distribution (version 4.0 or later, available from http://water.usgs.gov/software/libanne.html). Note that under Windows NT/2000/XP IOWDM must be compiled as a DOS executable (as opposed to a Windows console-mode executable). Subroutines within the LIBANNE util.lib library require the ANSI.SYS device driver, but ANSI.SYS is only supported for DOS applications and not for Windows applications under Windows NT/2000/XP. The Makefile used to compile the executable, using the Lahey Fortran 90 compiler and the Opus make program, is 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. F. RUNNING THE SOFTWARE If the option to modify the PATH environment variable was chosen during installation, IOWDM can be run in an MS-DOS Command Prompt window from any directory by typing "iowdm". 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\iowdm4.1\bin\iowdm" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run IOWDM by selecting the IOWDM shortcut from the Start menu. The shortcut is found under Programs, in the Program Folder specified during installation (default: USGS). The shortcut will run IOWDM 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. Out of environment space error ------------------------------ This error can occur when running IOWDM, including when running the verification tests. The error occurs when there is insufficient space to hold a new environment variable definition. You can avoid this error by initiating a new command shell and specifying how much environment space you need. For example, in an MS-DOS Command Prompt window, typing command /e:1024 will initiate a new command shell with 1024 bytes of environment space. Environment space can be between 256 and 32768 bytes. The above command will increase the environment space for only the current Command Prompt window. To permanently increase your environment space, on Windows 9x/Me machines, click the MS-DOS icon in the upper-left corner of the Command Prompt window and select Properties. Select the Memory tab and increase the value in the Initial environment field. On Windows NT/2000/XP machines, add the above command to C:\winnt\system32\config.nt and initiate and use a new MS-DOS Command Prompt window. G. TESTING Test data sets are provided to verify that the program is correctly installed and running on the system. The tests may also be looked at as examples of how to use the program. The tests are run in the test subdirectory. The data subdirectory contains the input data and the expected results for each test. Run the tests by first opening an MS-DOS Command Prompt window and changing to the test subdirectory by typing the following (substitute the drive letter and directory where you installed IOWDM, if you did not install it in the default location): c: cd "program files" cd usgs\iowdm4.1\test After each test is completed, compare the results to the expected results using a file comparison utility such as fc. If all goes well, the only differences that will appear will be in test7.exp in the values for the attributes DATCRE and DATMOD--the dates of data-set creation and last modification, respectively. To clean up after the tests, type the command: clean Notes: a) Some of the tests may require input generated by a previous test, so they should be run in sequential order. b) Test 7 requires the annie program (version 4.1 or later) Run the tests by following the steps below. Test 0: - Type "iowdm" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test0.log". IOWDM will be run using the keystrokes in ..\data\test0.log as if they were typed in. - The files test.wdm and error.fil will be produced. (In addition to possibly containing error messages, error.fil contains a record of some of the program operations executed.) Compare error.fil to ..\data\test0.err by typing: fc ..\data\test0.err error.fil Tests 1-6: - Type "iowdm" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\testN.log" where N is the number of the test, 1-6. IOWDM will be run using the keystrokes in ..\data\testN.log as if they were typed in. - The files testN.out and error.fil will be produced. Compare these files with the appropriate testN.out and testN.err files in the data subdirectory. For example, following test 1, type: fc ..\data\test1.out test1.out fc ..\data\test1.err error.fil Test 7: - Type "annie" to execute ANNIE (if the PATH environment variable was not modified upon installation of ANNIE so that ANNIE can be executed from any directory, type the full path name of annieX.X\bin\annie, where X.X is the version number of ANNIE; for example, "c:\program files\usgs\annie4.0\bin\annie"). - On the opening screen, type "@". In the small panel that appears, type "..\data\test7.log". ANNIE will be run using the keystrokes in ..\data\test7.log as if they were typed in. - The files test7.exp and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test7.exp test7.exp | more fc ..\data\test7.err error.fil The tests are described in the table below, where 'test' is the test number, 'program' is the program used to run the test, and the 'usage' column indicates how a file is used, with i for input, o for output. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 0 iowdm create wdm file command file test0.log i wdm file test.wdm o error file error.fil o 1 iowdm add attribute data from flat file to the wdm file command file test1.log i tabular formatted attributes test1.tfl i list formatted attributes test1.lfl i summary of data processed test1.out o wdm file test.wdm o error file error.fil o 2 iowdm add time-series data from flat file to the wdm file command file test2.log i flat file containing daily data test2.ft1 i flat file containing daily data test2.ft2 i summary of data processed test2.out o wdm file test.wdm o error file error.fil o 3 iowdm add watstore n-day values to the wdm file command file test3.log i watstore basin characteristics test3.bcd i watstore n-day values file test3.ndy i summary of data processed test3.out o wdm file test.wdm o error file error.fil o 4 iowdm add watstore basin characteristics and annual peak flows to wdm file command file test4.log i watstore basin characteristics test4.bcd i watstore annual peak flows test4.pks i summary of data processed test4.out o wdm file test.wdm o error file error.fil o 5 iowdm add watstore daily values to the wdm file command file test5.log i watstore daily values file test5.gsd i summary of data processed test5.out o wdm file test.wdm o error file error.fil o 6 iowdm add watstore unit values to the wdm file command file test6.log i watstore unit values file test6.gsu i summary of data processed test6.out o wdm file test.wdm o error file error.fil o 7 annie export data sets for verification command file test7.log i data management file test.wdm i export file test7.exp o error file error.fil o H. UNINSTALLING To uninstall IOWDM, double-click Add/Remove Programs in the Control Panel, select IOWDM 4.1, and click the Add/Remove button. Any user files in the IOWDM installation directory--such as those created in the test or user subdirectories--will be left behind intact. I. 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