U.S. GEOLOGICAL SURVEY DIGITAL DATA SERIES 37 Data from Selected U.S. Geological Survey National Stream Water-Quality Monitoring Networks (WQN) [This is the \DOCFILES\CUSTOMIZ.TXT file] GSMENU.DOC GSMENU.EXE 8.3 96/09/09 The GSMENU software system may be used to provide a flexible user-specified menu of executable programs and batch file instructions. GSMENU may also be used to run submenus, including submenus nested several levels deep. The GSMENU software system consists of GSMENU.EXE and GSMENUOV.EXE. Both must be present and in the same directory for the software to work. GSMENU.EXE is the main driver. It spawns GSMENUOV.EXE, which reads the menu data file and runs the menu. After a choice has been made GSMENUOV.EXE writes information about the menu option chosen to a file called GSMENU.CMD. GSMENU.EXE reads this file, and executes the program instructions. GSMENU requires about 16k of RAM to run. It spawns .EXE programs directly and invokes a second copy of COMMAND.COM to run DOS commands and .BAT files. The second invocation of COMMAND.COM requires an additional 3k of RAM to run. If there is insufficient RAM to run a menu program, an error message will be displayed. GSMENU reads a datafile (given as command line input), which specifies the menu configuration and execution instructions. This gives instructions on how to edit a menu data file for input to GSMENU. GSMENU may then be used to read it and run the programs or batch files listed. If an error is found in the menu data file, GSMENU will write GSMENU.ERR, which contains an error message about the menu data file. Below is an example of a EXAMPLE.MNU file which shows how to run EXE, COM, and BAT files, as well as how to call a submenu. All lines in the data file must be present and come in the order listed below. Message lines, menu lines, and the title line must end with a tilde (~). The tilde must be the last character on the line before a carriage return/line feed. If no menu title is desired, simply have a tilde as the first character on the title line. NOTE: The data file must be made with an ASCII editor, not a word processor. MENU COLORS The color attributes specify the colors used in the menu. The color attributes are specified with a 3 character string structured as follows: character 1 = foreground intensity L = low H = high character 2 = foreground color colors: R = Red character 3 = background color G = Green B = Blue Y = Yellow M = Magenta C = Cyan W = White K = blacK Example: HGK will give high-intensity green characters on a black background. LWB will give low intensity white characters on a blue background. MENU MESSAGES A message to the menu user may be displayed. The message will be enclosed in a box, with a maximum of five message lines, each with a maximum length of 76 characters. Each message line must be ended with a tilde (~). The box location is specified with an upper left corner row and column location, and the box and text colors may be specified as above. The number of message lines specified must agree with the number of actual message lines in the datafile. If no message display is desired, set the message top_line to -1, and the number of message lines to 0, and do not include any message lines in the file. In this case any values for message left_column and message color will be ignored, but a value must be provided for each. If blank lines are desired, put a space followed by a tilde. MENU TITLE If a title line is input, it will be printed on the top line of the menu box, if the menu box is long enough. If no title is desired, set title color = 0 and put a single tilde as the first character on the title line. MENU OPTIONS A minimum of two menu options must be defined. There may be a total of 15 options, excluding the ape line. The maximum length of a menu line is 60 characters. If a menu line has a character preceded by a left accent character (` = ASCII 96) in the line, that character will be highlighted and hitting that character will execute that option. However, highlighted characters may not be duplicated. The next_choice menu option to highlight may be specified in the menu data file. This allows a sequence of menu items to be run. NOTE: Normally GSMENU will run a menu option and then return to the menu upon completion of the option. However, if the option's next_choice flag is set to 0 (see example, Option 4), then GSMENU will run the option and NOT return to the menu. MENU COMMANDS Following the menu option strings is a section with the commands corresponding to each option. There are two lines of information for each of the menu options. The first line for each option contains the option number, used as a check, the number of command arguments, and the number of the next menu option to run after the current one is finished running. This allows sequencing choices in the menu. If the next menu option is 0, the GSMENU system will quit after running the current option. The second line contains the path\program name and the execution command. Following this are any command line arguments (optional). See options 2 and 4 for examples of how to specify arguments for EXE and COM files, with and without command line arguments. The command arguments must be separated by a comma, and must be listed in the order: PATH\PROGNAME.EXT,PROGNAME,ARG1,ARG2,ARG3,..., NOTE: GSMENU does not change to the drive\directory of the called program. If the called program requires additional files that are not in the path and are not accessible from the directory that GSMENU is in, it is better to put the command into a batch file that changes directory to the desired drive/directory. NOTE: The PATH\PROGNAME.EXE must not exceed 60 characters. NOTE: PROGNAME must not exceed 8 characters. NOTE: The string of arguments must not exceed 120 characters. RUNNING BATCH FILES A different format is required to run a batch file. You must invoke a copy of COMMAND.COM, which then runs the batch file. See option 3 for an example. The command arguments for a batch file must be listed in the order: COMMAND.COM,C:\,/C,C:\TEST\EXAMPLE.BAT, In this case the second argument tells where to look for COMMAND.COM, the third tells it to execute the following command, and the fourth is the name of the batch file to run. NOTE: No arguments may be fed to the batch file. RUNNING DOS COMMANDS A similar format is required to run a DOS command, such as DIR. You must invoke a copy of COMMAND.COM, which then runs the command. See option 1 for an example. The command arguments for a batch file must be listed in the order: COMMAND.COM,C:\,/C,DIR, In this case the second argument tells where to look for COMMAND.COM, the third tells it to execute the following command, and the fourth is the name of the DOS command to run. No arguments may be fed to the command. RUNNING SUBMENUS An example of a submenu is given in option 4. This option calls GSMENU.EXE with command line input of EXAMPLE2.MNU as the menu datafile. When the second invocation of GSMENU.EXE is aped, the program will return to the first invocation of GSMENU.EXE, running the commands contained in EXAMPLE.MNU. DO NOT call the previous menu from a submenu -- a loop results which your PC will not like at all. The call to run the submenu is recursive within the program. You are not really running the program again, but the software cues on the word "GSMENU" as argument 2, and calls the function which reads the specified menu file and runs the menu. No additional memory is required to run submenus. Menus may therefore be nested several levels deep. NOTE: Normally GSMENU will run a submenu and when the submenu is aped will return to the calling menu. However, if the submenu next_choice flag is set to 0 (see example, Option 4), then GSMENU will run submenu NOT return to the calling menu. The main menu/submenu structure must be arranged as a tree, with no loops. In the diagrams below, example menu structure 1 is acceptable, but example menu structure 2 is not. Example 1: Acceptable menu structure. Both SUBMENU1A and SUBMENU1B can call SUBMENU2B. There is no loop since SUBMENU2B cannot call any of the menus which are above it in the tree. 旼컴컴컴컴커 � MAINMENU � 읕컴컴컴컴켸 || || \/ \/ 旼컴컴컴컴컴� 旼컴컴컴컴컴� � SUBMENU1A � � SUBMENU1B � 읕컴컴컴컴컴� 읕컴컴컴컴컴� || || || || \/ \/ \/ \/ 旼컴컴컴컴컴� 旼컴컴컴컴컴� 旼컴컴컴컴컴� � SUBMENU2A � � SUBMENU2B � � SUBMENU2C � 읕컴컴컴컴컴� 읕컴컴컴컴컴� 읕컴컴컴컴컴� Example 2: Unacceptable menu structure. Both SUBMENU1A and SUBMENU1B can call SUBMENU2B. However, because SUBMENU2B can call SUBMENU1A, a loop results. 旼컴컴컴컴커 � MAINMENU � /=============\ 읕컴컴컴컴켸 || || || || || \/ \/ \/ || 旼컴컴컴컴컴� 旼컴컴컴컴컴� || � SUBMENU1A � � SUBMENU1B � || 읕컴컴컴컴컴� 읕컴컴컴컴컴� || || || || || || \/ \/ \/ \/ || 旼컴컴컴컴컴� 旼컴컴컴컴컴� 旼컴컴컴컴컴� || � SUBMENU2A � � SUBMENU2B � � SUBMENU2C � || 읕컴컴컴컴컴� 읕컴컴컴컴컴� 읕컴컴컴컴컴� || || \======================/ MENU DATA FILE ERRORS: If an error is found in the menu data file, GSMENU will write an error message describing the error to the screen. It will also write GSMENU.ERR, which contains the same error message about the menu data file. MENU EXECUTION ERRORS: If a program cannot be found, GSMENU will beep. EXAMPLE MENU DATA FILE: NOTE: In this example, comments are enclosed in square brackets. Comments are not normally included in menu data files. Lines should be left justified, except when indention is desired in messages or title. There should be no extra lines between the menu argument lines. EXAMPLE.MNU [name of GSMENU data file ] LWB HWR [colors of message box, message text; ] 3 5 [message box top line, left element; ] 1 [# of message lines to follow; ] This is an example of GSMENU version 8.2~ [message line ] LWK [color for menu title; ] EXAMPLE MENU~ [menu title line; ] LWB LWB HRB LBW [colors for menu box, options, hilited chars, bar;] 10 15 [menu box top line, left element; ] 4 [# of menu lines to follow; ] Show a `Directory~ [menu line 1 -- Run DOS command ] `Norton Edit a file~ [menu line 2 -- Run EXE file with command line arg] Run `TEST.BAT~ [menu line 3 -- Run BAT file ] Run Submenu `1 ~ [menu line 4 -- Run submenu ] 1 [menu start option ] 1 5 4 [Opt 1: number_args, next_option ] COMMAND.COM,C:\,/C,DIR,/o/p, [Opt 1: command.com name,path,arg 1, ] [ dos command,args ] 2 3 1 [Opt 2: number_args, next_option ] NE.EXE,NE,THISFILE.DOC, [Opt 2: path\program, command, args ] 3 4 1 [Opt 3: number_arguments, next_option ] COMMAND.COM,C:\,/C,TEST.BAT, [Opt 3: command.com name,path,arg 1, ] [ path\filename.BAT ] 4 3 0 [Opt 4: number_arguments, next_option ] GSMENU.EXE,GSMENU,EXAMPLE2.MNU, [Opt 4: path\program, command, ] [ path\menufile.ext ] VERSIONS: Ver: 1.0 Date: 06/14/92 Programmer: Buttleman 2.0 10/08/92 Buttleman Modified to add color choices for menu, menubox, message, message box, and highlight. Modified to remove default file name to force file name input. 3.0 01/26/93 Buttleman Modified to test input data file for acceptable input. 4.0 05/11/93 Buttleman Modified to use new POP_MENU, with ` to mark highlighted options keystrokes. 4.1 09/10/93 Buttleman Modified to malloc the pmenu structure, to use less RAM. 4.2 09/17/93 Buttleman Added hilite to line and used revised POP_MENU. 5.0 09/22/93 Buttleman Major revision to make submenu calls to GSMENU recursive. 6.0 11/04/93 Buttleman Added help capability. This allows the messages to be used for a title. Changed fscanf of message line to drop the \n and add SKIPREAD(). This allows indenting message lines. 6.1 11/18/93 Buttleman Fixed bug causing false error message if no menu title was provided. 6.2 11/24/93 Buttleman Fixed bug causing false error messages. Modified to read entire line with fscanf and then parse info out with sscanf, in order to give better error messages. 7.0 12/03/93 Buttleman Substantially revised to use modified POPX(), modified from POP_MENU(). Now uses only about 500 bytes each submenu. 7.1 12/16/93 Buttleman Fixed bug in reading title if no title was desired. 7.2 12/21/93 Buttleman Fixed bug in optdata->args, making last arg NULL. 7.3 03/08/94 Buttleman Slight revisions for smaller code. 7.31 03/31/94 Buttleman Fixed bug in title on menu. 7.4 07/13/94 Buttleman Increased stack size. 7.5 12/12/94 Buttleman Revised to switch to drive\dir of called program, then return to original drive\dir. Changed L_xxxxxx calls to W_xxxxxx calls to reduce size. Revised to save/restore original video mode. 8.0 95/11/24 Buttleman Completely revised to use spawned GSMENUOV.EXE, to read menu data file and run menu. Memory requirements cut to ~22K. 8.1 96/02/26 Buttleman Fixes bug in first menu startup choice. 8.2 96/03/28 Buttleman Changed to primitive file open/read/close functions to reduce memory requirements to about 16500 bytes. 8.3 96/09/09 Buttleman Revised to use explicit paths to overlays in spawns. WQN/GSSEARCH Browse Format Modifications In the \DOSMENU directory, there are 8 files for each of the 15 GSSEARCHable databases. The dbname.CFG file specifies the structure of the database to GSSEARCH. If desired, users may edit one or more of the existing browse formats specified in the dbname.CFG file. However, because the number of formats is limited to five, no additional browse formats may be specified. Formats may be modified by editing a copy of the dbname.CFG file using a pure ASCII text editor. DO NOT use a word-processor which creates a non-ASCII file. The browse formats are specified in the last lines of the dbname.CFG file. The specifications for each format consist of a format header line followed by a line of numbers specifying the data fields displayed. The format header line is simply a text string of no more than 78 characters, which is prefaced with a minus sign followed by the format number, and followed by a tilde (~), which acts as a stop. The second line of the format specifier consists of, at most, ten triads of numbers. The first number in each triad is the data field number. The second number is the browse format column, starting with zero as the column immediately to the right of the left double-bar border of the display panel. The third number is the number of characters in the field to display. Any portion of a data field which extends beyond the right edge of the display panel will be truncated. DO NOT MODIFY any other lines in the dbname.CFG file! To modify the dbname.CFG file, you must copy to the hard drive (the WQN96 directory which was created by the INSTALL program) before editing it. You must then modify the appropriate line in the WQN4.MNU file (already in the WQN96 directory). Change that line from r:\dosmenu\software\gssearch.exe,gssearch,r:\dosmenu\dbname,r:, to r:\dosmenu\software\gssearch.exe,gssearch,h:\wqn96\dbname,r:, where h: is the hard drive containing the WQN96 directory and r: is the CD-ROM drive.