DOCUMENTATION OF PROGRAM RETRVE FOR READING THE DATA FILES An algorithm named 'RETRVE.FOR' was developed to read in all the data files, i.e., daily weather, soil profile properties, soil organic residue, soil profile initial conditions, irrigation management, fertilizer management, treatment management, measured cotton crop harvest summary, and measured cotton intermediate growth data, which correspond to a particular treatment combination for a given year. A PC-based OTG ANSI FTN77 software package (University of Salford FTN77/386 revision C, P.O. Box 5250, 308 Mulberry Street, Scranton, PA 18505) was used as the developmental tool; therefore, all code complies with the ANSI standard and should be transportable to other FORTRAN compilers. Wherever possible, RETRVE.FOR was structured to adhere to the IBSNAT standard as closely as possible, as discussed in the 'File Structure and Data Formats' section of this document. Structure of RETRVE.FOR: RETRVE.FOR, contains a main routine, MAIN, and three subroutines, LISTID, READDA and VALFAB. MAIN will prompt the user to verify that the include file, 'PATHINP.INC', has been edited correctly. It then reads this file into the appropriate variables. MAIN calls subroutine LISTID which will use the information in the PATHINP.INC file to identify which files are to be retrieved. It also sets the path to those files. Subroutine LISTID then calls subroutine READDA. This routine will open both the files to be read and the output file, RETRVE.OUT. All files which contain variables to be interfaced with the simulation model are read in consecutive order by READDA. Files A and B, which are validation data files, are processed in a separate subroutine, VALFAB. All data read in are echoed into an output file, 'RETRVE.OUT'. File B data are loaded into a multidimensional array. An array indexing technique is employed to load the individual state variable arrays according to identification array, NV(I). These single dimensional arrays along with the JDOY array provide real world observed data which can be plotted along with simulated values from a plant growth model to validate the model's predictions. PATHINP.INC file: The 'CTEXPyy.DIR' files contain a list of all the file names associated with the results from a particular year's experiment. These files, therefore are the key to the database. An input file named PATHINP.INC is the control input file used by RETRVE.FOR to retrieve the desired files within the database. As illustrated in Table 2, it contains four lines. Each line corresponds to the following variables in the RETRVE.FOR algorithm. (1) EXPID - an 8 digit character string which identifies the experimental data set desired for a particular treatment combination within a year, ex. 'PX158701'. (2) DIRFN - sets the path and gives the file name of the desired year 'CTEXPyy.DIR'. For example, if you desire to extract data files from a 1987 experiment using your floppy drive A:, then set DIRFN to 'A:\CTEXTP87.DIR'; otherwise, if you have loaded the data files onto your hard drive, then simply set the path to the proper directory. For example, a subdirectory used to hold your FORTRAN data files could be used 'C:\FTN77\DATA87\CTEXTP87.DIR'. (3) PTODAT - sets the path to the directory which contains the actual data files for a given EXPID and year. This path must be set similarly to that in the previous example, i.e. 'A:\' for files located in floppy drive A:, and 'C:\FTN77\DATA87\' for the data files located in a \FTN77\DATA87\ subdirectory of your hard drive, C:, (4) NPATH - gives the number of characters used in the character string which sets the path in variable PTODAT; for example, if the path is set to the floppy drive A:\, 'A:\', then NPATH is 3. If it is set to 'C:\FTN77\DATA87\', then NPATH is set to 16. It is important that NPATH be set correctly so that the name of each file to be opened can be concatenated to the existing path, thereby enabling those files to be opened and eventually read by RETRVE.FOR. Note!, NPATH must not exceed 45 which limits the character string used to set the paths in both the DIRFN and PTODAT variables. Running RETRVE.FOR: After editing the PATHINP.INC file, and compiling and linking the source code in RETRVE.FOR, RETRVE is ready for execution. During a run it will prompt the user to verify that the PATHINP.INC file is set up correctly. The user should enter '1' if PATHINP.INC is correct; otherwise enter '2' to discontinue and edit PATHINP.INC. During execution, the complete path and file names being processed are echoed to the screen. This will allow verification that the correct files are being loaded. Output from RETRVE.FOR: Execution RETRVE will generate an output file called RETRVE.OUT. This file is output in the same directory that RETRVE is executed. It consists of nothing more than an echo of the input files read. This is a further check to verify that the actual data is the same as that in the text portion of the document. Interfacing algorithm RETRVE.FOR with a cotton simulation model: The RETRVE.FOR source code has been developed so that it can be readily interfaced with any cotton simulation model. After each of the input files has been opened in subroutine READDA, the variables within the file are read and can be interfaced directly with the corresponding variables in the cotton model being used, as illustrated by tables after each of the READ statements in READDA. The original source code makes these interface tables non-executable by having C's in the first column to make then comments. To use these interface tables, simply insert the variable names used in your model which correspond to the input variable names used in the IBSNAT standard. Check for consistency in units. If the units differ, a conversion factor can be used to scale the variables properly. Lastly, remove the C's so that the comments become executable statements, re-compile, link, and run the executable program. Table 1. example of a PATHINP.INC file used to extract data files located on a floppy inserted into drive A: (a), or on a subdirectory in the hard-drive C: (b), respectively. ___________________________________________ a) PX158701 A:\CTEXTP87.DIR A:\ 3 ___________________________________________ b) PX158701 C:\FTN77\DATA87\CTEXP87.DIR C:\FTN77\DATA87\ 16 ___________________________________________