Full Equations Utilities (FEQUTL) Model for the Approximation of Hydraulic Characteristics of Open Channels and Control Structures During Unsteady Flow

U.S. GEOLOGICAL SURVEY WATER-RESOURCES INVESTIGATIONS REPORT 97-4037

Input-Output Unit Number Selection

FEQUTL has been operational long enough that some components predate recent developments in operating systems. In the past, some versions of Fortran and some operating systems required that an input or output operation in a computer program must be associated with a file on a hard disk using a unit number. Thus, the user had to specify an explicit unit number in order to associate the file on the hard disk with the proper point of input or output in the Fortran program. In addition, it was not possible to reference a file name as such in Fortran programming in the past. Therefore, the intermediary of a unit number had to be applied.

As a consequence, a considerable history of input streams was developed for FEQUTL that required explicit unit numbers. These numbers continue to be supported in FEQUTL to maintain consistency with past use even though the use of unit numbers is no longer required in the current Fortran compilers and operating systems. As time permits and demand dictates, the old usage of unit numbers will be replaced with new usage that applies the more flexible facilities available on current operating systems. In the interim, the following guidelines for choosing unit numbers are offered.

1. Each operating system/language combination has a unique upper limit for unit numbers. In some cases, this is 99, but it may be larger or smaller than this value. The purpose of MUNIT in the INCLUDE file ARSIZE.PRM is to set this level so that the input can be checked in FEQUTL computations to make sure that the specified unit numbers are not too large for the operating system.
2. Fortran programming has defined standard unit numbers since the early beginning of the language, in the 1960's. Unit 5 was defined as a standard input, unit 6 as standard output to a line printer, and unit 7 was defined as output to a standard card punch. Card punches are not used anymore, and line printers are rarely used at this time.
3. Command-line arguments are used in FEQUTL. A command line is the line following the DOS prompt on a computer that uses the DOS operating system and the UNIX prompt on a computer that uses the UNIX operating system. This is the line where words and strings of symbols are typed to tell the computer what actions should be done (the line where commands are issued to the computer). The first item entered on a command line is the command. Items that follow the command, usually separated from the command and from each other by one or more spaces, are called command-line arguments. Three arguments are required in FEQUTL simulation. The first argument is the name of the file that contains the input to FEQUTL as defined in the Input Description for the Full Equations Utilities Model (section 5). This is the standard input file. The second argument is the name of the file that contains the items that are computed in the course of a simulation. This is the standard output file. The third argument is the name of the file that contains the tables computed with FEQUTL. This is the standard table file. An example command line for FEQUTL is
   FEQUTL FEQUTL.IN FEQUTL.OUT FEQUTL.TAB where
   
   FEQUTL.IN is the name of the standard input file,
   
   FEQUTL.OUT is the name of the standard output file, and
   
   FEQUTL.TAB is the standard table file.

   The names for these three files are selected by the user and can be any valid name available in the operating system. As many as 64 characters may be used for the specification of the file name in FEQUTL. Therefore, a path can be included with the name.

   Two standard unit numbers that relate to the standard input and standard output files for FEQUTL are defined in a file STDUN.PRM, which may be retrieved electronically as described in section 1.1. These are the unit numbers that are equivalent in concept to unit numbers 5 and 6 in traditional Fortran. The Fortran parameter STD5 defines the unit number to use for processing the standard input file. The Fortran parameter STD6 defines the number to use for processing the standard output file. These parameters are 5 and 6, respectively, by default for DOS systems, but they need not have those values. The values included in STDUN.PRM are STD5 = 35 and STD6 = 36, but any valid values that the user selects may be used. Once selected, however, the unit numbers cannot be used for another purpose in the input to FEQUTL.

   The Fortran-defined unit designation for writing to the display screen is used in FEQUTL. The unit field in an output statement in Fortran is given as an asterisk to denote output to the display screen. This means that an output to the standard output unit, STD6, will appear in the standard output file, whereas an output to a unit designated by an asterisk is to the display screen. This is the result on DOS systems. Some UNIX systems, however, define the asterisk unit differently. On these UNIX systems, the asterisk unit is associated with the standard output unit, 6. If this also is the unit used for the standard output file, then no text is written to the display screen and all text appears in the standard output file. Therefore, to write to the display screen when running the program under UNIX, do not assign number 6 to STD6. Also, the standard unit number 5 is commonly associated with the keyboard in some UNIX systems. Therefore, STD5 and STD6 should not have the values of 5 and 6 under UNIX, but should be given some other numbers before the program is compiled. Values of 3 and 4 have been used in the past and have worked. On UNIX systems, unit numbers 5, 6, and 7 should be avoided because they may have a special meaning.

   Aside from the standard unit numbers specified for STD5 and STD6 and the traditional standard unit numbers of 5, 6, and 7, the user may select the unit numbers. This choice is limited only by the following constraints.
   

   1. The same unit number should not be used more than once in any context other than the input of files containing function tables.

   2. A unit number larger than the maximum value set by parameter MUNIT in the INCLUDE file ARSIZE.PRM at the time the program was compiled should not be used.

   The units that have been referenced in FEQUTL simulation are monitored, and any duplicate reference results in an error.

   Standard numbers are recommended for files that appear in a common context. Five additional unit numbers are defined in the file STDUN.PRM to describe these common contexts. In FEQUTL, STD7 is used to process the function-table file computed with FEQUTL; STD10 is used in floodway computations; and STD48, STD49, and STD50 are used in the HEC2X (section 5.15) and WSPROX (section 5.23) commands. The values included in STDUN.PRM are STD7 = 7, STD10 = 10, STD48 = 48, STD49 = 49, and STD50 = 50, but any values that the user selects may be valid.