README.TXT EXAMS II Exposure Analysis Modeling System Installation and Execution Version 2.94 February 1990 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 File Name and Content Development System Installation Routine Execution Run Time and Performance Minimum File Configuration Modification Technical Contact Disclaimer INTRODUCTION ------------ The Exposure Analysis Modeling System (EXAMS II) executes both steady-state and dynamic models designed for rapid evaluation of the behavior of synthetic organic chemicals in lakes, rivers, and estuaries. EXAMS is an interactive program that allows the user to: o specify and store the properties of chemicals and ecosystems, o modify the characteristics of either via simple English- like commands, o and conduct rapid, efficient evaluations of the probable fate of chemicals. This release of EXAMS II allows for two simultaneous chemicals or one chemical with a single degradation product. It also provides for environmental models with a maximum of thirty-two segments. The microcomputer release of EXAMS II is a full implementation of the VAX/VMS release of EXAMS II. The microcomputer implementation of this program performs the same function as the U.S. EPA mainframe/minicomputer version. DOCUMENTATION ------------- It is recommended that the user obtain the following document for reference: Exposure Analysis Modeling System (EXAMS): User Manual and System Documentation EPA/600/3-82/023 NTIS Accession No. PB82 258 096 Domestic Cost: $45.00 Foreign Cost: $90.00 This document is applicable to the microcomputer, VAX, and other mainframe/minicomputer installations of the U.S. EPA release of the EXAMS II program. This document should be retained by the requester for future reference. This document can be ordered from the National Technical Information Service (NTIS) at the address shown below. Please use the correct accession number when ordering and note the approximate cost of the document. National Technical Information Service (NTIS) 5285 Port Royal Road Springfield, VA 22161 703/487-4650 Copies of the following documents are included in the distribution set (See FILE NAME AND CONTENT and MINIMUM FILE CONFIGURATION sections): Document Name File Name ------------- --------- EXAMS II Installation and Execution README.TXT EXAMS II User's Guide MANUAL.TXT NOTE: The file, MANUAL.TXT, is identical to the EPA publication, "Exposure Analysis Modeling System: Reference Manual for EXAMS II" -- EPA/600/3-89/084. After being copied to the hard disk (see INSTALLATION section), these ASCII text files can be displayed on the monitor screen by using the DOS TYPE command (e.g., TYPE README.TXT) or printed using the DOS PRINT command (e.g., PRINT README.TXT). FILE NAME AND CONTENT --------------------- After executing the self-extracting installation file, INSTALEX.EXE, the following files will be found on your system. See the INSTALLATION section for details. README.TXT - This document is an ASCII text file that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. EXAMS.EXE - Executable task image file for the EXAMS II program. EXAMDAF.DAT - An unformatted, direct access data and help file that is read automatically by EXAMS II. This file has space for 25 chemical data sets, 10 environmental data sets, 5 external chemical load series, and 5 product chemistries. EXAMS.OVL - Overlay segment file for EXAMS II executable task image file EXAMS.EXE. TEST.EXA - Sample input data file used to test the installation of EXAMS II on a microcomputer system. To test the installation, execute EXAMS II using the file TEST.EXA as the name of the input file (see INSTALLATION section). See the explanation of the TESTOUT.DAT file for file comparison procedures. NOTE: An input file name entered by the user during the execution of the EXAMS II program must be a unique and valid DOS file name. The input file name must also be a valid EXAMS II command input data set name -- either furnished with the distribution package (see FILE NAME AND CONTENT section) or designated by the user. The data set will be processed and executed in this run of the program. Remember, a DOS file name can be from 1 to 8 characters and can have an optional 1 to 3 character file name extension. TESTOUT.DAT - Output listing file produced by EXAMS II using the test input data file TEST.EXA. First, test the program using the test data file TEST.EXA as the input file. Then, compare the contents of the output file produced (REPORT.DAT) with the output file provided (TESTOUT.DAT). To compare file contents, use the DOS (COMP) or MS-DOS (FC) file compare command. See the INSTALLATION section for further details. MANUAL.TXT - The EXAMS II User's Guide. This is an ASCII text file that can be displayed on the monitor screen using the DOS TYPE command or printed using the PRINT command. RMFORT.ERR - Run time error message library file for Ryan- McFarland FORTRAN (tm) (RMFORT) (see DEVELOPMENT SYSTEM section). RETURN1.ANS - An empty file containing a single carriage return character used to provide an key or null response to an input prompt in selected DOS batch command files. RETURNY.ANS - A file containing a "Y" followed by a carriage return character used to provide a "Y" or "yes" response to an input prompt in selected DOS batch command files. ANSWER.COM - Executable code file used in DOS batch command files to compile and link the EXAMS II and UTILITY programs. The ANSWER program writes screen prompts and reads the user response entered from the keyboard. NOTE: The execution of the following DOS batch command files is NOT required to execute and use the EXAMS II program. CLEXAMS.BAT - DOS batch command file used to compile and link edit the EXAMS II program FORTRAN source code files (*.INC and *.FOR files in \EXAMS\INCL_INC and \EXAMS\EXAMSFOR sub-directories) to incorporate changes made in the source code file(s) by the user. See the program listing for complete in-code documentation. The execution of this command produces a new executable task image file for the EXAMS II program. It will only need to be executed if changes have been made in the FORTRAN source code, NOT the input data files provided by the user. To execute, type CLEXAMS at the DOS system prompt, then press the key. CL_UTIL.BAT - DOS batch command file used to compile and link edit the UTILITY program FORTRAN source code files (*.INC and *.FOR files in \EXAMS\INCL_INC and \EXAMS\UTIL_FOR sub-directories) to incorporate changes made in the source code file(s) by the user. See the program listing for complete in-code documentation. The execution of this command produces a new executable task image file for the UTILITY program. It will only need to be executed if changes have been made in the FORTRAN source code or the *.DAT files read by the UTILITY program (see FILE NAME AND CONTENT section). To execute, type CL_UTIL at the DOS system prompt, then press the key. EXAMS.LNK - PLINK86 Plus (tm) (see DEVELOPMENT SYSTEM section) link edit command file for the EXAMS II program code. This file is called and executed automatically by the compile and link edit DOS batch command file CLEXAMS.BAT. UTILITY.LNK - PLINK86 Plus (tm) (see DEVELOPMENT SYSTEM section) link edit command file for the UTILITY program code. This file is called and executed automatically by the compile and link edit DOS batch command file CL_UTIL.BAT. *.INC - FORTRAN source code "include" files containing FORTRAN COMMON block declarations for the EXAMS II and UTILITY programs. These files are automatically included or "copied" into the appropriate FORTRAN source code file (*.FOR) during compilation. These files are stored in the DOS sub-directory \EXAMS\INCL_INC. *.FOR - FORTRAN source code files for the EXAMS II program and UTILITY program, version 2.94. These files are stored in the DOS sub-directories \EXAMS\EXAMSFOR and \EXAMS\UTIL_FOR. ENCANON.DAT - Formatted, sequential files read automatically by SPECS.DAT the UTILITY program to build the unformatted, CHEMDAT.DAT direct access data and help file EXAMDAF.DAT. TYPE.DAT HELPVAR.DAT HELPFIL.DAT SETUP.EXA - EXAMS II input command file used to initialize a new direct access data and help file EXAMDAF.DAT built by the UTILITY program. NEWDAF.BAT - DOS batch command file to build a new EXAMS direct access, data and help file, EXAMDAF.DAT. This command file assumes that the DOS batch command file CL_UTIL.BAT has been successfully executed to build a UTILITY program executable task image file UTILITY.EXE. DEVELOPMENT SYSTEM ------------------ The following list describes the language and program development tools used by the Center for Exposure Assessment Modeling to build version 2.94 of the microcomputer implementation of EXAMS II. Also shown are the recommended minimum hardware and software configuration and the recommended \CONFIG.SYS configuration/environment file statements for the implementation and execution of the EXAMS II program and all related support files and programs. Make sure that the IBM PC or compatible system has these statements in the \CONFIG.SYS file, and re-boot the system to implement these changes in the root directory before attempting to install or use the EXAMS II program. Development System: Language: FORTRAN 77 Operating System: DOS version 4.01. The program also works with 2.12 and later versions and IBM DOS or MS DOS 3.2x and 3.3x. Compiler: Ryan-McFarland FORTRAN (tm) RMFORT version 2.43 Link Editor: PLINK86 Plus (tm) version 2.24 Overlay Structure: Yes. See file EXAMS.LNK and UTILITY.LNK files included with source code for up and down FORTRAN subroutine calling sequence and structure. Storage Requirements: (k=1,024; m=1,048,576) Random Access Memory: (maximum use in EXAMS II program) 457k free bytes needed to execute EXAMS II program Use DOS CHKDSK command to verify bytes free in RAM memory. See paper entitled "CEAM MODELS AND THE DOS OPERATING ENVIRONMENT" by David Disney (December 1988) for further information on RAM requirements. Hard Disk Drive: 20m byte drive recommended (minimum) Installation Size: Run Time: Approx. 2.88m bytes max. FOR Code: Approx. 1.02m bytes max. Document: Approx. 0.20m bytes max. ------ Total 4.10m bytes (Total does not include *.OBJ files if all programs are recompiled and linked.) Run time size: Up to approximately 1.93m bytes (without compressed files) plus space for user input data files, output, and temporary files produced by the EXAMS II program (see MINIMUM FILE CONFIGURATION section). Numerical Coprocessor: Optional. Executable task image file contains coprocessor emulation code. However, coprocessor will greatly improve program execution speed. \CONFIG.SYS Statements: For a detailed explanation of the following configuration file statements, see paper entitled "CEAM MODELS AND THE DOS OPERATING ENVIRONMENT" by David Disney (December 1988). BREAK=ON BUFFERS=20 FILES=20 DEVICE=C:\ANSI.SYS - and - SHELL=C:\COMMAND.COM C:\ /E:1024 /P - for DOS 3.2x, 3.3x, and 4.01 - - or - SHELL=C:\COMMAND.COM C:\ /E:50 /P - for DOS 3.1x and earlier versions - (Use DOS VER command to determine DOS version number.) INSTALLATION ------------ Create and/or edit the configuration/environment system file \CONFIG.SYS on the "boot" or start-up disk drive to contain the statements suggested in the DEVELOPMENT SYSTEM section. Remember, these changes will not be in effect until the system is re-booted (i.e. power off/power on or use the warm boot procedure by holding down the keys at the same time and pressing the key). To install the EXAMS II program on an IBM PC or compatible microcomputer system, execute the following step-by-step instructions to transfer the contents of INSTALEX.EXE to a hard disk drive and decompress the EXAMS II program and all support files and programs. Step Number and Description Command at DOS Prompt --------------------------- --------------------- 1 - Set the default drive to the n: hard disk (e.g., hard disk "n:" - e.g., C:): 2 - Execute the installation file INSTALEX to decompress all essential EXAMS II run time files: 3 - Execute the EXAMS II program EXAMS with the test input data file provided (TEST.EXA). NOTE: After an opening screen is displayed, the prompt "EXAMS->" will appear on the monitor screen. At this prompt enter DO TEST, then press the key. This step will begin the execution of the program using the input test data file TEST.EXA. 4 - Compare the contents of the test COMP REPORT.DAT TESTOUT.DAT output file produced (REPORT.DAT) with the sample output file supplied (TESTOUT.DAT): NOTE: For MS-DOS, the file compare command is "FC". ROUTINE EXECUTION ----------------- 1) Make sure to (a) complete the installation instructions shown in the INSTALLATION section to make the program and all related files resident on the hard disk drive (usually designated as "C:") and (b) modify the \CONFIG.SYS system environment file. This needs to be executed only once for a given installation. 2) Change the DOS default sub-directory to the EXAMS sub-directory by using the DOS CD (change directory) command at the DOS system prompt: CD \EXAMS. 3) To execute the EXAMS II program, type EXAMS at the DOS system prompt, then press the key. After an opening screen, the prompt "EXAMS->" will appear on the monitor screen. At this prompt, the user can enter valid EXAMS II program commands. See the User's Guide (MANUAL.TXT) for further information. NOTE: The EXAMS II program uses logical unit number (LUN) seven (7), writing to device name "PRN", for its "print" command. Support for the print command option can be loaded into RAM memory prior to executing the program. To initialize and make the DOS PRINT command memory resident, enter PRINT at the DOS system prompt, then press the key TWICE. This step needs to be executed only once for each warm () or cold (power off/on) start of the microcomputer. The response entered by the user for an input file name must be a unique and valid DOS file name. The input file name must also be a valid EXAMS II program input data set name either 1) as furnished with the distribution package (see FILE NAME AND CONTENT section) or 2) as designated by the user. Any input "DO" file name can have an optional 1 to 3 character file name extension. However, the file name extension ".EXA" is reserved 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 II program prompt. Examples: EXAMS-> DO TEST (file name is TEST.EXA) EXAMS-> DO MYDATA.DAT This data set will be processed during the execution of the program. The file names used for the input data and output listing files (except for the test input and output case provided) are arbitrary, but must follow the rules for DOS file names. A file name should assist the user in identifying the contents or purpose of the file (e.g., INPUT.DAT, OUTPUT.OUT). Any input and/or output file name can be from 1 to 8 characters and can have an optional 1 to 3 character file name extension. Any characters beyond 8 in the file name or beyond 3 in the file name extension will be truncated by the DOS operating system. See the DOS Reference Manual for further information on file names and disk file input/output procedures, rules, and commands. This implementation of the EXAMS II program has the same function and will follow the same execution sequence as the VAX/VMS implementation for version 2.94 RUN TIME AND PERFORMANCE ------------------------ The following run time (approximate) was observed using EXAMS II test data set TEST.EXA for the microcomputer. This input test data set is not intended to be representative of a full scale program simulation. It was developed to test the installation of significant sections of the EXAMS II code. The following run time was produced on an IBM PS/2 model 80 using DOS 4.01, 640k bytes of random access memory, a 70 megabyte hard disk, a 16 megahertz clock, and an 80387 math numerical coprocessor. A significantly slower run time (6+ minutes) can be expected on standard XT/AT/PS2 class machines with a smaller disk drive and slower CPU clock speed. Data Set Name Approx. Run Time (hr:min:sec) ------------- ---------------- TEST.EXA --- 00:01:33 Please note that program run time and performance can be affected by many microcomputer system and program parameters such as: o available disk space o available memory o CONFIG.SYS file options and parameter values o disk storage fragmentation o and use of a math coprocessor chip. MINIMUM FILE CONFIGURATION -------------------------- The following list describes the recommended minimum file configuration needed to test and execute the EXAMS II program and support DOS batch command files. This list assumes that o the EXAMS II program has been successfully installed (see INSTALLATION section) from the distribution file o the user has defined and stored all application-specific run time files. All other EXAMS II program files can be deleted if the user needs to recover disk space. - README.TXT - Installation and Execution support documentation. - TEST.EXA - Sample input data file. - EXAMS.EXE - Executable code file for microcomputer. - EXAMDAF.DAT - Unformatted, direct access data and help file. - RMFORT.ERR - Ryan-McFarland (tm) FORTRAN run time error message library file. - TESTOUT.DAT - Sample output file using test input data file TEST.EXA. - MANUAL.TXT - EXAMS II program User's Guide. MODIFICATION ------------ Included in the distribution set are: o an executable task image for the EXAMS II program o FORTRAN source code files for IBM PC and compatible microcomputer systems o batch command files to compile and link the task images. Please note that the RMFORT (tm) FORTRAN compiler and the PLINK86 Plus (tm) link editor are NOT required to execute any portion of the EXAMS II program. If the user wishes to modify the program, it will be up to the user to supply and/or obtain the following: o an appropriate text editor that saves files in ASCII (text) format, o and FORTRAN program development tools to recompile and link edit any portion of the EXAMS II program and/or UTILITY program. The CEAM cannot support, maintain, and/or be responsible for modifications that change the function of the EXAMS II program executable task image file (EXAMS.EXE), the UTILITY program executable task image file (UTILITY.EXE), and/or the DOS batch command files supplied with this program package. TECHNICAL 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/ DISCLAIMER ---------- Mention of trade names or use of commercial products does not constitute endorsement or recommendation for use by the United States Environmental Protection Agency. The EXAMS II program must be used at the user's own risk. Neither the U.S. EPA nor the program author can assume responsibility for program content, output, interpretation, or usage. ######################### DWD/dwd/las - February 1990 - E:\EXAMS\README.TXT Revised - March 2004