U.S. GEOLOGICAL SURVEY WATER-RESOURCES INVESTIGATIONS REPORT 93-4076 HYDRO-CLIMATIC DATA NETWORK (HCDN) STREAMFLOW DATA SET, 1874-1988 [This is the \DOCFILES\HCDR.DOC file] Hydro-Climatic Data Retrieval (HCDR) INTRODUCTION The HCDR program allows you to search for and select any of the 1659 stations in the Hydro-Climatic Data Network using a variety of criteria. You can display station information, sort stations you have selected according to station or data characteristics, and output the streamflow data in several formats. GETTING STARTED When using the program for the first time, type "@tutor.log" when the opening screen appears. This will invoke a tutorial, which will walk you through the program, displaying a series of pop-up boxes with instructions. Read and follow the instructions. The following sections in this document provide information on program options, screen interaction, modification of screen appearance and interaction, details of program execution, and additional available software. PROGRAM OVERVIEW The menu structure of HCDR is diagrammed below. Use of the program follows three basic steps: 1) Choosing stations from the HCDN data base, 2) Viewing station characteristics, and 3) Producing output of the streamflow data. HCDR ___________|___________ | | | ________ ________ ________ | | | | | | | Choose | | View | | Output | |________| |________| |________| ________ | | | Choose | |________| ___________________________________|___________________________________ | | | | | | | | | Location Watershed Time pd Channel Meteorologic View Get Add/Omit Sort - STAID - DAREA - #YRS - DATUM - PRECIP - HUCODE - NONCDA - BEGYR - SLOPE - I24-2. - LATDEG - ELEV - ENDYR - LENGTH - JANMIN - LNGDEG - SOILIN - LAKE - GLACER - STCODE - FOREST - STORAG ________ | | | View | |________| ______|_______ | | Table Detail ________ | | | Output | |________| _________________|___________________ | | | | | | Export Flat Wdm Daily Table Detail The "Choose" option can be used to select all stations within a specified latitude or longitude, in specific states, or having a period of record within a certain range of years. Many other criteria can be selected for use in searching the HCDN data base. Minimum and maximum or other appropriate values are specified for each criterion selected. "Get" is selected to perform the search. The two options under the "View" option will display information on the selected stations. "Table" displays a table of user-chosen station characteristics, one station per row, while "Detail" displays all characteristics defined for each station, one station per screen. The streamflow data of the selected stations can be output in a number of formats using the "Output" option. "Export" is used to convert the data, stored in the Watershed Data Management (WDM) binary format, to ASCII for porting to a non-DOS-based computer for the creation of a WDM file in that computer's internal binary format (see ADDITIONAL SOFTWARE). "Flat" outputs the data in a format which can be read by spreadsheet and statistics software. "Wdm" will produce a WDM file of selected data; this would be useful in creating a subset of the HCDN data for use with other software that uses WDM files as input. "Daily" produces a printout of daily values, one table per year. A monthly minimum, maximum, and mean are included at the bottom of each table. "Table" and "Detail" provide the same information as the options under "View," but output is redirected to a file. SCREEN INTERACTION The best way to learn how to use the program is to run the tutorial. An overview of the program interface is provided in this section. Interface Basics Four types of screens make up the interface: menu, form fill-in, file name, and informational text screens. Commands for displaying help information, moving to previous or following screens, and displaying allowable ranges for input values are available on each screen as applicable. Each screen consists of at least two boxed-in regions, or windows. These two regions are the data window and the instruction window. A third region, the assistance window, can be displayed or removed from the screen as desired. Beneath the windows, the available commands appear, with their associated function keys. The figure below shows the basic layout of the screens in HCDR. +-screen name (path)------------------------program name and version-+ | | | | | | | | | Data window | | | | | | | | | | | +--------------------------------------------------------------------+ +-assistance type----------------------------------------------------+ | | | Assistance window | | | | | +--------------------------------------------------------------------+ +-instruction type---------------------------------------------------+ | | | Instruction window | | | +--------------------------------------------------------------------+ Help:F1 Accept:F2 Prev:F4 Limits:F5 Quiet:F8 Cmhlp Oops All three windows and the line of available commands can be viewed on an 80x24 character screen. Each window has a distinct purpose. User interaction with the program takes place in the data window where menus, input forms, and informational text are displayed. The instruction window contains information on the keystrokes necessary to interact with the program. Error messages related to invalid keystrokes are also displayed in the instruction window. When error messages are displayed, the instruction type in the upper left-hand corner of the window changes from the usual "INSTRUCT" to "ERROR." In the assistance window, help information, valid ranges for input values, and details on program status can be displayed. Each screen has a name which is placed where the words "screen name" appear in the above figure. The first screen is called the Opening Screen. All subsequent screens are given a name based on the menu option selected. Screen names are followed by a path--a list of characters which represent the keystrokes made to arrive at the current screen. This list of keystrokes can aid in keeping track of where the current screen falls in the menu hierarchy. The assistance window appears when the commands Help, Cmhlp, Limits, Status, or Xpad are chosen. The name of the command chosen is placed in the upper left-hand corner of the assistance window, where the words "assistance type" appear in the figure above. The assistance window can be closed by choosing the Quiet command. The table below describes each of the commands available. Keys Command Pressed Function to Invoke* ------- --------- -------------------------------------------- Help F1 Displays help information in the assistance or ;h window. Help information is available for menu options and for input fields on form fill-in and file name screens. Once Help has been chosen, the help information displayed is updated as different screen elements are highlighted and as different screens are displayed. The program automatically closes the assistance window if a screen is reached for which there is no help information. Accept F2 Indicates that you have "accepted" the or ;a input values, menu option currently highlighted, or text message in the data window. Causes program execution to continue. Cmhlp F3 c Displays brief descriptions of the commands or ;c available on the current screen. Oops F3 o Redraws screen. Default values replace any or ;o values that have been entered. Available on form fill-in and file name screens. Prev F4 Re-displays the previous screen. Available or ;p on most form fill-in screens and file name input screens. The program does not read any input values previously entered if Prev is chosen. Limits F5 Displays valid ranges for numeric input, and or ;l possible responses for character input on form fill-in and file name screens. As with the Help command, information on input limits is updated as different screen elements are highlighted by using the arrow keys or the Enter key. Intrpt F6 Interrupts current processing loop, return- or ;i ing program to point of execution previous to current process. Status F7 Displays the number of stations currently or ;s selected. Quiet F8 Closes the assistance window. Available or ;q only if the assistance window is open. Xpad F9 Opens the assistance window as a "scratch or ;x pad," for recording notes, questions, or other information to be referred to when done executing the program. Text entered is saved in a file named "XPAD.DAT". * The function keys will work to invoke the commands on most systems. For those systems where this is not the case, the semicolon key (";") followed by the first letter of the command can be pressed instead. Most commands are invoked by pressing a single function key. The Accept command, associated with the F2 function key, is used most frequently in the process of using the program. Those commands not invoked by a single function key are chosen by pressing the F3 function key or the semicolon key (";") followed by the first letter of the command. Pressing either the F3 key or the semicolon key causes the cursor to be placed at the bottom of the screen; any command can then be invoked by typing its first letter. Pressing either of these keys a second time without invoking any command will reactivate the data window. The F3 key and the semicolon key are also used to reactivate the data window when the assistance window becomes the active window on the screen. This occurs when a command has been chosen that opens the assistance window, and there is more information to be displayed than can be viewed at one time in the four-line window. The line of commands at the bottom of the screen disappears and directions are given in the instruction window as to how to scroll through the text displayed in the assistance window. Pressing the F3 key or the semicolon key at this point restores the line of commands and reactivates the data window. Interaction in the Data Window Menu selections in the data window can be made by highlighting the desired option through use of the arrow keys and then invoking the Accept command. Alternatively, the first letter of the desired menu option can be typed. If more than one menu option begins with the same letter, enough characters must be typed to uniquely identify the desired option. Form fill-in screens may require character input, such as a yes/no response or numeric input. There are also option fields that can be toggled on or off by pressing the space bar. Movement of the cursor around these screens is accomplished through use of the arrow keys or the Enter key. File name screens contain one input field into which a file name is typed. File names entered are checked for validity; warnings are issued for invalid file names, and opportunity is given to enter a valid file name. Informational text screens are displayed to give information on tasks in progress or already completed, as well as to give explanatory information or error messages. When these screens are displayed, use the Accept command to continue. MODIFICATION OF SCREEN APPEARANCE AND INTERACTION Screen characteristics such as color and the default response of the function keys and the Enter key may be modified through parameters contained in a "TERM.DAT" file. Each time HCDR is run, the TERM.DAT file is read if it exists and values read from the file replace the default system values. Function keys F1 through F9, with the exclusion of F3, can be remapped to any command. The TERM.DAT parameters PFKEY1, PFKEY2, PFKEY4, ..., PFKEY9 are assigned the first letter of the command to which the function key should correspond. On menus, file name screens, and text screens, the Enter key is currently set to respond as if you had invoked Accept on that screen. The TERM.DAT parameter which corresponds to Enter key response, "MENCRA," has been given a default value of "NEXT," causing the program to continue on to the next screen when the Enter key is pressed. Alternate values for MENCRA are "NONE" and "DOWN." If you included a line containing "MENCRA NONE" in a TERM.DAT file, the Enter key would have no effect when pressed for menus, file name screens, or text screens. Setting the value of MENCRA to "DOWN," however, would cause the Enter key to function on menu screens as if you had pressed the down arrow: the highlight bar would move to the next menu option. On file name and text screens a value of "DOWN" for MENCRA has no effect. Note that on form fill-in screens, the Enter key always serves to move the highlight bar to the next field, unless the last field on the screen is currently highlighted and MENCRA is set to "NEXT". In this case, pressing the Enter key causes the Accept command to be invoked and the program continues to the next screen. The following table describes the TERM.DAT parameters that can be assigned values. Each parameter included in the TERM.DAT file is placed on a separate line, followed by its assigned value. At least one space must separate the parameter from its value. The TERM.DAT file must be placed in the location defined in the "AIDE.PTH" file, as described in the next section. Default Allowable Parameter value values Definition --------- ------- --------- ----------------------------------- CLRFRS 15 0 to 15 standard foreground color CLRBKS 4 0 to 15 standard background color CLRFRE 14 0 to 15 foreground color for error messages CLRBKE 12 0 to 15 background color for error messages CLRFRD 14 0 to 15 color of first letter of commands when cursor is on command line PFKEY1 H H,A,C,O,P, F1 function key assignment L,I,S,Q,X PFKEY2 A H,A,C,O,P, F2 function key assignment L,I,S,Q,X PFKEY4 P H,A,C,O,P, F4 function key assignment L,I,S,Q,X PFKEY5 L H,A,C,O,P, F5 function key assignment L,I,S,Q,X PFKEY6 I H,A,C,O,P, F6 function key assignment L,I,S,Q,X PFKEY7 S H,A,C,O,P, F7 function key assignment L,I,S,Q,X PFKEY8 Q H,A,C,O,P, F8 function key assignment L,I,S,Q,X PFKEY9 X H,A,C,O,P, F9 function key assignment L,I,S,Q,X MENCRA NEXT NEXT Enter key response DOWN NONE PROGRAM EXECUTION NOTES Each time HCDR is run, three files are created: HCDR.LOG, XPAD.DAT, and ERROR.FIL. HCDR.LOG contains all the keystrokes entered during the most recent execution of the program. The file, or portions of the file, can be used in subsequent program runs as a macro, the keystrokes being read from the file as if they were typed interactively. To use the file in this way, change its name to something other than "HCDR.LOG," edit the portion you want to use as a macro, and, after invoking HCDR, type "@filename" on the screen where you want the macro to begin, where "filename" is the new name you have given the file. The file XPAD.DAT contains all text typed into the XPAD window as described in the table on commands. ERROR.FIL contains output from debugging statements, providing documentation of program execution if any problem arises. The above three files are placed, by default, in the HCDN92 directory. The placement of the files can be modified by specifying an alternate drive and path name in the "AIDE.PTH" file in the HCDN92 directory. The placement of the files may also be specified via an environment variable by typing "set AIDE.PTH=X:\xxxx". ADDITIONAL SOFTWARE Additional software is available to read data in the WDM format, and other software is in development. The program ANNIE, which can be purchased for a nominal fee, provides an option to construct WDM files from "Export"ed data. ANNIE can also plot hydrographs at any time step for any duration, list and edit data in a WDM file, and perform streamflow data analyses such as flow duration analysis, computation of n-day low or high flow annual series, and frequency analysis on annual series. Other programs in development - or not yet distributed on the PC - perform base flow separation, analyze trends, determine biologically-based low flows, or map locations of stations. Contact the U.S. Geological Survey, NAWDEX Office, (703) 648-5676, in Reston, Virginia, for more information.