File: README.TXT EXAMS Exposure Analysis Modeling System Version 2.98.04.03 U.S. EPA Release, May 2004 Center for Exposure Assessment Modeling (CEAM) National Exposure Research Lab - Ecosystems Research Division Office of Research and Development (ORD) U.S. Environmental Protection Agency (U.S. EPA) 960 College Station Road Athens, Georgia 30605-2700 706/355-8400 _____________________________________________________________________________ CONTENTS Introduction Documentation Installation Completing and Testing the Installation Selected File Names and Content Fortran Source Code Files Development System Routine Execution Run Time and Performance Modification Technical Help Contact Disclaimers _____________________________________________________________________________ INTRODUCTION The Exposure Analysis Modeling System, first published in 1982 (EPA-600/3-82-023), provides interactive computer software for formulating aquatic ecosystem models and rapidly evaluating the fate, transport, and exposure concentrations of synthetic organic chemicals - pesticides, industrial materials, and leachates from disposal sites. EXAMS contains an integrated Database Management System (DBMS) specifically designed for storage and management of project databases required by the software. User interaction is provided by a full-featured Command Line Interface (CLI), context-sensitive help menus, an on-line data dictionary and CLI user's guide, and plotting capabilities for review of output data. EXAMS provides 20 output tables that document the input data sets and provide integrated results summaries for aid in ecological risk assessments. For a list of modifications to the EXAMS model system refer to the file RELEASE.TXT. For convenience, the terms "EXAMS model system" and "EXAMS" will be used in this document to refer to the EXAMS model and all associated support files and programs as a single unit. Therefore, the terms "EXAMS", and "EXAMS model system" are synonymous for purposes of this document. Throughout this document, the symbol "" represents pressing the or carriage return key. Responses and key strokes that can be typed by the user are underlined with the hyphen character (-) or enclosed by the angle bracket characters (<>). _____________________________________________________________________________ DOCUMENTATION It is recommended that the user obtain and refer to the documents listed below to operate and apply the EXAMS model system. Copies of the following documents are included within the Internet distribution file Install_EXAMS.EXE. Document Name(s) File Name(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~ EXAMS model system general execution and README.TXT user support guide EXAMS Model System Release Notes RELEASE.TXT (Enhancements/updates/additions; may not be covered in user manual file) EXAMS Model System Abstract ABSTRACT.TXT The EXAMS User's Manual can be viewed or downloaded from the U.S. EPA CEAM Internet site (http://www.epa.gov/ceampubl/swater/exams/exams29804/EXAMREVG.PDF): EXAMS User's Manual EXAMSREVG.PDF "Exposure Analysis Modeling System (EXAMS): User Manual and System Documentation" EPA/600/R-00/081 These documents should be retained by the requester for reference. _____________________________________________________________________________ INSTALLATION This model system is designed for the Intel family of microcomputers or compatible systems running under Windows 95, 98, NT, or 2000 operating systems (refer to DEVELOPMENT SYSTEM section). Properly configured, this model system and its support files and programs can be executed under a Windows 95/98/NT/2000 operating system DOS console or window. Follow the instructions shown on the interactive installation program screens and menus to install, decompress (extract), and restore file(s) to their original name and size in order to place the EXAMS model system in a usable format on a hard or virtual disk. For comparison purposes, the original date and time of creation are also restored with each file. The following procedure will install the EXAMS model system from the file "Install_EXAMS.EXE" downloaded from the Internet: From the desktop, select (click on) the My Computer icon. Browse for, then click on the file Install_EXAMS.EXE. Follow instructions and respond to prompts presented on the monitor screen by the interactive installation program. This is a compressed, self-extracting, interactive installation program that contains the EXAMS model system. This installation program assumes that the current default drive and sub-directory/folder is the same drive and sub-directory/folder that contains the file Install_EXAMS.EXE. For further information and to access CEAM software products through the Internet, refer to the TECHNICAL HELP CONTACT section. _____________________________________________________________________________ COMPLETING AND TESTING THE INSTALLATION The file "TEST.EXA" is an input command file that verifies successful installation by exercising a substantial subset of EXAMS' capabilities, followed by comparison to the expected output from the example simulation as contained in the file "TESTOUT.XMS" supplied with the program. Execution (not installation per se) of the EXAMS model system may be incompatible with Windows 95/98 software cache files SMARTDRV.SYS or SMARTDRV.EXE loaded from the system configuration files CONFIG.SYS or AUTOEXEC.BAT on the boot drive. If the EXAMS model system prematurely halts, produces unusual results, or causes the host system to halt or hang, remove any SMARTDRV statements on the boot drive CONFIG.SYS or AUTOEXEC.BAT files and re-boot the system to implement these changes before attempting to reuse any portion of the EXAMS model system. The EXAMS model system is a Windows application executed from the command line prompt within a Windows console (DOS window) from within Microsoft Windows 95/98/NT/2000. EXAMS accesses extended memory through Windows services. Under a Windows console, all virtual memory is available to the program. Under Windows 95/98, improved performance can be achieved by setting memory properties of the DOS console as follows: a) right click mouse on MS-DOS or Console icon b) click on Properties from menu bar c) select Memory tab d) set Expanded (EMS) memory to "None" e) set all other memory settings to "Auto" (see f/g below for exception) f) select MS-DOS protected-mode (DPMI) memory g) set DPMI memory value to 65535 DOS Storage Path ~~~~~~~~~~~~~~~~ Verify that the EXAMS model system executable task image file (EXAMS.EXE), run time support files (*.DAF) and the test command file (TEST.EXA) are in the current default sub-directory/folder. It is convenient, but not required, to have these files, as well as user-designed input data and command files, in the same sub-directory/folder. However, to execute the EXAMS model or program from any selected (e.g., project) sub-directory/folder located on a hard or virtual disk drive, try adding the EXAMS installation sub-directory/folder (e.g., C:\EXAMS) to the DOS search PATH, and copy EXAMS' run time support files (*.DAF) to the current default sub-directory/folder. One way to accomplish this is to add or modify the PATH statement in the system start-up file AUTOEXEC.BAT (located in the root directory on the start-up or boot drive). For example SET PATH=%PATH%;C:\EXAMS Under Windows 95/98, this modification of the search path can also be accomplished by adding, for example, the string "path %path%;C:\EXAMS" to the "batch file" area of the console properties "program" tab. Refer to the DOS or Windows Reference Manual, or on-line help for PATH command and AUTOEXEC.BAT file application and use. The following steps are designed to be executed from within a Windows DOS console or window running under Windows 95, 98, NT, or 2000 to test the EXAMS installation: Step Description/Action ~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1) Set the default drive to the disk containing the model system sub-directory/folder: A:\> C: -- 2) Change the Windows DOS console default sub-directory/folder to the sub-directory/folder selected during installation as the target sub-directory/folder (e.g., C:\EXAMS or C:\PIRANHA\EXAMS). Use the DOS CD (change directory) command at the console prompt: C:\> CD \EXAMS --------- 3) Execute the EXAMS model: C:\EXAMS> EXAMS ----- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXAMS version 2.98.04.03 run time initial information status screen and run-time prompt displayed here. Follow and respond to the input or command prompts displayed on the monitor screen. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Welcome to EXAMS Release 2.98.04 Exposure Analysis Modeling System Technical Contact: Lawrence A. Burns, Ph.D. U.S. Environmental Protection Agency 960 College Station Road Athens, GA 30605-2700 USA Phone: (706) 355-8119 (Fax) 355-8104 Email: burns.lawrence@epa.gov Latest Maintenance 2004-05-21 Type HELP and press the RETURN key for command names, HELP USER for a summary of command functions, HELP PAGES for a list of information pages, or HELP EXAMS for introductory information. Please stand by while EXAMS checks the computational precision of this computer and initializes the Activity Data Base. EXAMS-> DO TEST ------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXAMS 2.98.04.03 run time diagnostic and information status screens, messages, and run-time prompts may be displayed while the model executes. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When the EXAMS model finishes executing, compare the output file supplied to that produced -- for example: C:\EXAMS> FC OUT_TEST\TESTOUT.XMS REPORT.XMS ---------------------------------- A lack of differences between these files confirms successful installation. _____________________________________________________________________________ SELECTED FILE NAMES AND CONTENT The self-extracting installation program is compressed to save disk space and file transfer time. This section contains a description of selected files that can be decompressed from the installation program. Execution of the Install_EXAMS.EXE command extracts EXAMS model system files. These files are automatically stored into sub-directories/folders on the hard disk. The hard disk and sub-directory/folder structure, under which the sub-directories/folders shown below are stored, is selected by the user (e.g., C:\EXAMS or C:\PIRANHA\EXAMS) during execution of Install_EXAMS.EXE. If EXAMS is installed as part of the PIRANHA model system, the "InstallationDirectory" should be, for example, C:\PIRANHA\EXAMS. The string "InstallationDirectory" will be used to denote the highest level default installation directory/folder structure (e.g., C:\EXAMS) chosen by the user. Below the installation sub-directory/folder, all files are grouped and listed by the appropriate sub-directory/folder name into which they will be automatically stored. Unless specified as a "binary" file (e.g., *.DAF, *.PLT, *.EXE) in their description herein, EXAMS model input command and output listing files are ASCII (non-binary) text files. ASCII text files can be viewed or edited using any editor program that can read and save a file to disk in ASCII text (non-binary) format. For further explanation, information, or listings of example input and output data files, refer to the user's manual. ** Sub-directory/Folder InstallationDirectory: EXAMS.EXE - Executable task image file for the EXAMS model. This task image allows space for five simultaneous chemicals (or one chemical and two degradation products, etc.), and environmental models of up to one hundred segments. EXAMS.DAF - Unformatted, direct access (binary) data and help file read automatically by the EXAMS executable task image file (i.e., EXAMS.EXE) with space for 25 chemical data sets, 10 environmental data sets, 5 external chemical load series, and 5 product chemistries. OZONE.DAF - Unformatted, direct access (binary) file read automatically by the EXAMS executable task image file (EXAMS.EXE). This file contains a global data base of total column ozone from the TOMS (Total Ozone Mapping Spectrometer) flown on the Nimbus-7 spacecraft. TEST.EXA - "DO" input command file to test the installation and demonstrate application of the EXAMS model. To test the installation, execute the EXAMS model using this file as the name of an EXAMS input command "DO" file as described under INSTALLATION in this document. This command file is also furnished to provide instruction by example and can be used as a template for the preparation of a new or modified input command file. ** Sub-directory/Folder InstallationDirectory\OUT_TEST: TESTOUT.XMS - EXAMS tabular output listing file produced by executing the EXAMS model using the test input "DO" command file (TEST.EXA) provided with the distribution package. Installation is tested by executing the EXAMS model using the test input command file (TEST.EXA), then comparing the contents of the tabular output file produced (i.e., REPORT.XMS) with the corresponding test output file provided (e.g., OUT_TEST\TESTOUT.XMS). Special Run Time Files ** Sub-directory/Folder InstallationDirectory: The following files are not distributed with the distribution release. They are either created or updated (appended to) automatically when the user executes the EXAMS model (EXAMS.EXE) to process data interactively or within a run-time command file (e.g., TEST.EXA). These files will be stored in the sub-directory/folder (e.g.,\EXAMS) selected by the user during the installation of the EXAMS model system, or in the default directory in effect when EXAMS is executed. REPORT.XMS - EXAMS tabular output file (non-binary, ASCII). KINOUT.PLT - EXAMS direct access (binary) output file used to plot results of dynamic simulations. SSOUT.PLT - EXAMS direct access (binary) output file used to plot steady-state results. FGETSEXP.XMS - FGETS exposure file (non-binary, ASCII). FGETSCMD.XMS - FGETS command file (non-binary, ASCII). BASSEXP.XMS - BASS exposure file (non-binary, ASCII). HWIREXP.XMS - HWIR exposure file (non-binary, ASCII). _____________________________________________________________________________ FORTRAN SOURCE CODE FILES The Fortran source code files that build the U.S. EPA release of EXAMS are available for download from the CEAM Web site. Fortran source is NOT required to document, execute, or test any model, program, or associated run time support file as provided. EXAMS is a complex model system. The model source code relies on multiple interdependencies. Modification and recompilation of the Fortran source code files should be attempted only by experienced research personnel with substantial expertise in exposure analysis modeling. Such applications are intended for additional research and development, including comparison to field or laboratory data, other theories, and further enhancements, such as graphical interfaces. THE SEPARATE USE OF EXAMS FORTRAN MODULES OUTSIDE THE EXAMS SHELL IS NOT RECOMMENDED BY THE U.S. EPA FOR ROUTINE APPLICATIONS OR ENVIRONMENTAL IMPACT STATEMENTS. _____________________________________________________________________________ DEVELOPMENT SYSTEM The following list describes the language and program development tools used by the U.S. EPA Center for Exposure Assessment Modeling to build version 2.98.04.03 of the microcomputer implementation of the EXAMS model system. Also shown are the recommended minimum hardware and software configuration for implementation and execution of this model system and all related support files and programs. If the system upon which EXAMS is to be installed does not conform to minimum specifications, EXAMS WILL NOT execute properly. Development System: Hardware System: Fully IBM compatible 80386, 80486, or 80586/Pentium Language: Fortran 95 Operating System: Properly configured, this model system should work on hardware platforms within a Windows console under Windows 95, 98, NT, or 2000. Compiler: Lahey/Fujitsu Fortran 95 (LF95) Link Editor: PharLap 386|Link 9.2 Overlay Structure: None - linked as flat memory model and program Storage Requirements: (K=1,024; M=1,048,576) Hard Disk Drive: 100M byte drive recommended with 20M bytes free Installation Size: Run Time: Approx. 10M bytes Run time size: After installation, up to approximately 1M bytes, plus space for user input data or command files, output, and temporary files produced by model system. Numerical Coprocessor: Required. Printer Software: For *.PDF file only, Adobe Acrobat Reader. _____________________________________________________________________________ ROUTINE EXECUTION Introduction ~~~~~~~~~~~~ Complete the installation process to make the full or any portion of the EXAMS model system and related files resident on a hard (usually designated as "C:") or virtual disk drive. This includes at a minimum EXAMS.EXE, EXAMS.DAF, and OZONE.DAF, although in the absence of OZONE.DAF EXAMS will use zonal mean values (at 5 degree latitude intervals) for stratospheric ozone concentrations. Routine Execution Steps ~~~~~~~~~~~~~~~~~~~~~~~ The following steps are designed to be executed from within a Windows DOS console running under Windows 95/98/NT/2000. It is also possible to execute the EXAMS model by clicking on the My Computer icon from the user's Windows desktop, browsing for and clicking on the EXAMS.EXE file. Step Description/Action ~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1) Set the default drive to the disk containing the EXAMS model system sub-directory/folder. For example: A:\> C: -- 2) Change the default sub-directory/folder to the sub-directory/folder designated by the user during the installation program as the installation sub-directory/folder (e.g., C:\EXAMS or C:\PIRANHA\EXAMS). Use the DOS CD (change directory) command at the Windows console (DOS system) prompt: C:\> CD \EXAMS --------- 3) To execute the EXAMS model, type: C:\EXAMS> EXAMS ----- The prompt "EXAMS->" will appear on the monitor screen to prompt the user for information, data, commands, or a "DO" command file needed for this run of the model. At this prompt, the user can enter valid EXAMS model/program commands. Refer to the user's manual for further information on valid command usage and syntax. Viewing Output Results ~~~~~~~~~~~~~~~~~~~~~~ After executing an EXAMS model system executable task image file, results can be viewed in tabular format and as data plots using EXAMS commands. After exiting EXAMS and returning to the DOS prompt, the user can view those output files (e.g., REPORT.XMS), if any, produced by the execution of the program or model if and only if the file is in ASCII text (non-binary) format. Results can be viewed by scrolling through the output file that was (1) a result of model or program execution or (2) named by the user at a run-time prompt using EXAMS' "print," "write," or "plot" commands. A word processor or text editor is convenient for this purpose, or the command TYPE filename | MORE can be used where "filename" is the name of the output file. File Name and Path Specifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An input or output file name path specification or file name, as typed at a run time prompt or as specified by the user within an EXAMS "DO" input command file, may in general be given any arbitrary name convenient to the user, although it must be a unique and valid Windows path or file name. A file name should assist with identifying the contents or purpose of a file (e.g., INPUT.DAT, OUTPUT.LST, Test_the_Program.now). An input command or data file name must also be a valid EXAMS file name-- either furnished with the distribution package (see the SELECTED FILE NAMES AND CONTENT section) or created, designated, and named by the user. A file name typed at a run time prompt or specified within an EXAMS "DO" command input file will be processed and executed in a given run of the model. An EXAMS "DO" input command file, for batch processing of the EXAMS model, should only be created or modified using an editor program that can read and save a file to disk in ASCII text (non-binary) format. A "DO" input command file can be used to execute the EXAMS model in batch mode; it must contain valid responses to the interactive prompts presented during execution of the EXAMS model. Using an input "DO" command file allows the program to run without user intervention or interruption, and may be set up for multiple response or input data. This technique is useful to execute the model repeatedly while changing, for example, one input parameter between model executions without having to enter or modify other parameters, and for linkage to multi-year simulations from PRZM. An EXAMS model input "DO" command file name includes a conventional DOS 1- to 3-character file name extension. However, the file name extension ".EXA" is assumed for "DO" command files. If a file name extension other than ".EXA" is used for a "DO" command file, the extension must be entered with the file name at the EXAMS program prompt. Examples: EXAMS-> DO TEST (file name is actually TEST.EXA) EXAMS-> DO MYDATA.DAT EXAMS-> DO Test_the_Program.now An EXAMS "DO" command file will be processed during the execution of the EXAMS program. _____________________________________________________________________________ RUN TIME AND PERFORMANCE The following run time (approximate) was observed using the test input data files as furnished with the distribution version of the EXAMS model system. This time was obtained using input test data that may not be representative of a more complex "real world" problems and data. The test data and file have been furnished for testing the installation of the EXAMS model system and for instruction by example. In general, the input test data is not intended to be representative of full scale model simulations. It was developed to test the installation of significant sections of model code. The run time listed in the table below was produced on a Dell OptiPlex GX110 667 megahertz microcomputer running under a DOS window, under Windows 98, and using 640k bytes of random access (low end) memory (RAM) with 128 megabytes of extended memory. A significantly slower run time is possible on a computer system with less memory, slower central processing unit (CPU), and less disk space. ** EXAMS Model System Test Run Input Command File Approx. Run Time (min:sec) ~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~ TEST.EXA 0:01 Program run time and performance can be affected by many microcomputer system and program parameters including o available disk space o available memory o processor/CPU classification o CONFIG.SYS and AUTOEXEC.BAT file options and parameter values o disk file storage or fragmentation _____________________________________________________________________________ MODIFICATION Included with the distribution release is an executable task image file for the EXAMS model system. A Fortran compiler and link editor are NOT required to execute any portion of the EXAMS model system. For further information concerning modification of code, refer to the FORTRAN SOURCE CODE FILES section. The U.S. EPA CEAM cannot support, maintain, or be responsible for modifications that change the function of any executable task image file (EXAMS.EXE) supplied with this model package. _____________________________________________________________________________ TECHNICAL HELP CONTACT For questions or information concerning o installation and testing of the EXAMS model system and support programs or files, call 706/355-8400 for assistance or send mail via Internet to ceam@epamail.epa.gov o EXAMS model content, application, or theory, contact Lawrence A. Burns, Ph.D., 706/355-8119, FAX: 706/355-8104, Internet Email: burns.lawrence@epa.gov or at the address shown below o other support available through CEAM, contact Mr. Frank Stancil, U.S. EPA CEAM Manager - by mail at the following address Center for Exposure Assessment Modeling (CEAM) National Exposure Research Laboratory - Ecosystems Research Division U.S. Environmental Protection Agency (U.S. EPA) 960 College Station Road Athens, Georgia 30605-2700 - by telephone at 706/355-8100 - by fax at 706/355-8104 To help technical staff provide better assistance, write down a response to the following topics before calling or writing. If calling, be at the computer, with the computer on, and in the proper sub-directory/folder (e.g., C:\EXAMS) when the call is placed. o program information: - describe the problem, including the exact wording of any error or warning message(s) - list the exact steps, command(s), or keyboard key sequence that will reproduce the problem o machine information: - list computer brand and model - list available RAM (as reported by DOS CHKDSK or MEM command) - list extended memory present and free (XMS) - list name and version of extended memory (XMS) manager (i.e., HIMEM, VDISK, RAMDRIVE, etc.) - list available hard disk space (as reported by DOS CHKDSK command) - list the brand and version of DOS (as reported by DOS VER command) - list the name of any memory resident (TSR) program(s) installed NOTE: If contacting CEAM by mail or fax, include responses to the above information within correspondence. CEAM software products and their status are available through the Internet at the following Uniform Resource Locator (URL): http://www.epa.gov/ceampubl/ _____________________________________________________________________________ DISCLAIMERS Mention of trade names or use of commercial products does not constitute endorsement or recommendation for use by the United States Environmental Protection Agency. Execution of any portion of the EXAMS model system, and modification made to the system configuration files (i.e., CONFIG.SYS and AUTOEXEC.BAT) must be used or made at the user's own risk. Neither the U.S. EPA nor the program author(s) can assume responsibility for model or program modification, content, output, interpretation, or usage. The EXAMS program and files have been extensively tested and verified. However, as with all complex software products, the programs herein may not be completely free of errors and may not be applicable to all cases. In no event will the U.S. EPA be liable for direct, indirect, special, incidental, or consequential damages arising out of the use of the programs or associated documentation. CEAM can provide selected or limited scientific and application support for selected products if the user demonstrates that a given product is installed and working correctly using the test input data files provided with the distribution release. #########################