README.TXT CAP Culvert Analysis Program CAP - Version 97-08c 1999/11/15 Instructions for installation, execution, and testing are provided below. After installation, see the file doc\Cap.txt in the CAP installation directory for summary information on CAP. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. For all versions of Microsoft Windows, this DOS version of CAP must be installed and run using an MS-DOS Command Prompt window. TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DISTRIBUTION FILES C. DOCUMENTATION D. INSTALLING o Installing CAP o CAP directory structure o Making CAP easily accessible E. COMPILING F. RUNNING THE SOFTWARE G. TESTING A. SYSTEM REQUIREMENTS For installation of CAP, 1.1 megabytes of free disk space is needed. To run CAP, the following are necessary: - 386 or greater processor - math coprocessor - 64 kilobytes of free extended memory B. DISTRIBUTION FILES The following self-extracting DOS distribution files (containing the software, test data sets, and information files) are currently available. cp9708c.exe - Compiled using Lahey Fortran 90 cp9708cs.exe - Source code only C. DOCUMENTATION Bodhaine, G.L., 1968, Measurement of peak discharges at culverts by indirect methods: U.S. Geological Survey Techniques of Water-Resources Investigations, book 3, chap. A3, 60 p. Fulford, J.M., 1998, User's guide to the U.S. Geological Survey Culvert Analysis Program, Version 97-08: U.S. Geological Survey Water-Resources Investigations Report 98-4166, 70 p. A Portable Document Format (PDF) file of the above report can be found after installation in the doc subdirectory; for other formats of the report, see http://water.usgs.gov/software/Cap.html. Printed copies of most USGS publications can be obtained from: USGS Information Services Box 25286 Denver Federal Center Denver, CO 80225 electronic mail: infoservices@usgs.gov Phone: 1-888-ASK-USGS D. INSTALLING Installing CAP -------------- These instructions assume that you are installing the software in directory c:\Program Files\usgs, which we recommend. You may use other directories or disk drives, but you must change each occurrence of "c:" and "\progra~1\usgs" in all of the following instructions to the alternate location that you choose. Follow the steps below to install CAP from a distribution file. The steps make use of DOS commands which, for all versions of Microsoft Windows, must be executed in an MS-DOS Command Prompt window. 1. Move to the directory containing the distribution file; for example: c: cd \mydir The directory Cap97.08c is created (or overwritten) upon extracting the files contained in the distribution file. If the Cap97.08c directory already exists, you may want to delete or rename it before performing the next step. 2. Extract the files using the command: cp9708c -d c:\progra~1\usgs Substitute "cp9708cs" for "cp9708c" if you are installing the source-code distribution. Be sure to include the -d (restore directory structure) option. Note that "progra~1" is how the "Program Files" directory must be referenced in the above command since "Program Files" exceeds DOS's 8-character limit for directory names. CAP directory structure ----------------------- The following directory structure will be created (the contents of each directory are shown to the right): Cap97.08c file NOTICE.TXT and this README.TXT file `-----bin compiled executable and Lahey error file `-----doc documentation files (see file Contents.txt) `-----src Makefile and source code `-----test batch files to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin subdirectory is not included in the cp9708cs.exe distribution; it is created during compilation. b) Source code is included only with the cp9708cs.exe distribution. c) It is recommended that no user files be kept in the Cap97.08c directory structure. If you plan to put files in the Cap97.08c directory structure, do so only by creating subdirectories. Making CAP easily accessible ---------------------------- To make the CAP program accessible from any directory, without needing to type the full pathname of the software's location, the Cap97.08c\bin directory must be included in the PATH environment variable. On Windows 9x systems, add the following line to the end of AUTOEXEC.BAT: PATH=%PATH%;c:\progra~1\usgs\cap97.08c\bin Reboot your system after modifying AUTOEXEC.BAT. On Windows NT systems, from the Start menu, select Settings and then Control Panel. Double-click System and select the Environment tab. Enter "PATH" in the Variable field and enter "%PATH%;c:\progra~1\usgs\cap97.08c\bin" in the Value field. Click Set and then click OK. Initiate and use a new MS-DOS Command Prompt window after making this change. E. COMPILING The source code is provided in the cp9708cs.exe distribution 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, b) familiarity with the compiler and the operating system under which the compiler runs (i.e., DOS or Windows). As provided in the cp9708cs.exe distribution, the Makefile and source code are set up for use with the Lahey Fortran 90 compiler and the Opus make program. To generate a new executable, do the following: 1. Change directory to the source directory: cd Cap97.08c\src 2. Modify the beginning of the file named Makefile to correctly specify system-dependent variables: FC Fortran compiler name FFLAGS Fortran compiler flags LNKFLGS Fortran linker flags 3. Use the make program to initiate compilation of the source code and installation of the software: make [BINDIR=directory_for_executable] where the optional BINDIR variable is used to specify a directory already included in the PATH environment variable. The above make command will: a. create the directory Cap97.08c\bin if it does not exist, b. compile the source code, c. place the executable (Cap.exe) in Cap97.08c\bin, and d. place a copy of the executable in BINDIR, if specified. F. RUNNING THE SOFTWARE CAP has been compiled using the Lahey Fortran 90 compiler version 4.5. The file "LF90.EER" (from the Lahey compiler) located in Cap97.08c\bin contains error messages. If an error occurs, this file is used to print error messages if the Cap97.08c\bin directory is included in the PATH environment variable; if LF90.EER cannot be found, the error will only be identified by number. After CAP is properly installed (see INSTALLING, above) in a directory that is included in your PATH, the program can be executed by typing "cap". CAP prompts for type of program output (detailed report or table), output file name, run title, input file name containing culvert geometry, the culvert section id, input file name containing approach data, and approach cross section id. 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. Tests are run in the Cap97.08c\test directory. The directory Cap97.08c\data contains the CAP input data and expected results for each test. To test the installation, in an MS-DOS Command Prompt window change to the Cap97.08c\test directory: c: cd "program files" cd usgs\cap97.08c\test Execute the tests by typing the command: test [m [n]] where: m = the number of the first test to perform, default=1 n = the number of the last test to perform, default=7 For example: command what happens ------------------ ------------------------------------ test runs all of the tests test n runs test 'n' through the last test test n m runs test 'n' through 'm' After the tests are completed, the results are compared to the expected results. If all goes well, there should be no differences. To clean up after the tests, type the command: clean The tests are described in the table below. Test is the test number and the usage column indicates how a file is used, with i for input and o for output. test description of test and files file name & usage ---- -------------------------------------------- ----------------- 1 Mercer Creek culvert example CAP input data mercer.dat i Program output mercer.out o 2 Pigeon House Creek culvert example CAP input data pigeon.dat i Program output pigeon.out o 3 Rio Grande Conveyance Channel example, barrels 1 and 2 CAP input data riogran.dat i Program output--barrel 1 riogran1.out o Program output--barrel 2 riogran2.out o 4 TWRI creek culvert example based on examples 3 and 5 in USGS Techniques of Water-Resources Investigations (TWRI), book 3, chapter A3 CAP input data cultwri.dat i Program output cultwri.out o Three-parameter table report TABLES30.DAT o 5 TWRI concrete pipe culvert example based on TWRI example 8; metric units and *CC records used for culvert computations CAP input data twri8.dat i Program output twri8.out o 6 Vertical elliptical culvert section example CAP input data vellip.dat i Program output vellip.out o 7 Vertical elliptical culvert section example using *CS records CAP input data vellipcs.dat i Program output vellipcs.out o