GSSEARCH.DOC GSSEARCH.EXE 94/07/15 SYSTEM REQUIREMENTS o IBM or compatible personal computer o 640 kb RAM (at least 500 kb free memory) o MS- or PC-DOS version 3.3 or later o Microsoft MSCDEX version 2.1 or later o CD-ROM drive with ISO 9660 software driver o Hard disc drive (1 Mb free) o VGA graphics card o VGA color monitor o A Microsoft-compatible mouse is highly recommended GSSEARCH requires about 500 kb of RAM to run, but will use expanded or extended memory if available, and also uses overlays to improve its efficiency. SOFTWARE LIMITATIONS GSSEARCH will now handle an unlimited number of hits for searches and display. However, adjacency searching is limited to 32000 hits. For record display, the maximum record length is 32 kb, and the maximum number of lines in the full record display is 1000. GSSEARCH uses four 64 kb buffers for sorting and merging the "hit" record addresses. For the browse and full record display, it uses buffers 1 and 2 for the record addresses. The browse display is stored in the first 2400 bytes of buffer 3. The full record display line addresses are loaded into the next 10000 bytes. The record record display software loads as many records as it can (up to fifteen at a time) into the remainder of buffer 3 and all of buffer 4. If there is insufficient memory, fewer records will be loaded for the browse display. It also allocates memory from RAM for record output tags, so you may have insufficient memory to output a large number of records. GSSEARCH COMMAND LINE FORMAT GSSEARCH requires command line input of several items of information. The REQUIRED command line format is: GSSEARCH path\cfg_prefix x [options] path\cfg_prefix path and file name prefix of configuration file. x drive letter to prefix to database file names in configuration file. The OPTIONAL command line format is: /B Black & White display . /D=c Delimited output delimiting character . c = ASCII character; default = " /M=n Mouse double-click time sensitivity, in thousandth of a second. n = 50..250, 50 = most sensitive; default = 100 Recommended values: 150 for 80486 @ 66MHz 130 for 80486 @ 25MHz 100 for 80386 @ 20MHz /P=output_path Default path for output files. /G=grfpath Default path for .GRF output files. /L=x Lat/Lon conversion flag SUM for MAPPER software .GRF file output. MAPPER requires decimal degrees, and presumes S lats and W lons are negative. Default is no conversion. 1 = lat to negative lat. 2 = lon to negative lon. 4 = DDMMSS lat & DDDMMSS lon to decimal lat & lon. Example: /L=3 will convert both lats and lons to negative. NOTE: If a data base has both N & S lats and/or both E & W lons, all S lats and W lons must be converted to negative. The software reads the path\cfg_prefix from the command line and appends ".CFG" to it, to derive the database configuration file name. It then reads the data base file names contained in the configuration file (prefixing the database drive letter to them) to derive the database path\names. The file names in the configuration file MUST NOT contain a drive letter as part of the path. NOTE: As of GSSEARCH version 4.0, any of the command line options may be appended to the end of the .CFG file. However, command line input will override any information input in the .CFG file. REQUIRED FILES GSSEARCH.MSG File This file provides the run-time error messages for GSSEARCH. It is provided with GSSEARCH.EXE and must be in the same directory as GSSEARCH.EXE. GSSEARCH.HLP File This file provides the on-line help information for GSSEARCH.EXE program help. It is provided with GSSEARCH.EXE and must be in the same directory as GSSEARCH.EXE. DO NOT attempt to read it or edit it. db_name.CFG File Database configuration file db_name.GBG File Database data file db_name.LV1 .. db_name.LV4 Files Database index file db_name.HLP File This file provides the on-line data base help information for GSSEARCH. It provides general help information on the database and specific help information on the individual indexes in the data base. It must be in the same directory and must have the same name prefix as the data base files. It may be made by using GSMK_HLP.EXE to process individual help files to make the combined help file. The individual help files must be pure ASCII (i.e. made with an ASCII editor, not a word processor), and must not have lines which are longer than 78 characters. There may be a general data base information file, as well as information files for each index used in the data base. The resulting file has a header of 4000 bytes which contains offsets to the individual help topics, followed by the text for the help topics. See the section on GSMK_HLP.EXE for information on the command line format for GSMK_HLP. NOTE: The combined help file may NOT be edited directly. You must edit the individual help text files and then build the .HLP file. The general database help text file must have a name format of: xxxxx.TXT where xxxxx = help file name prefix (5 character max) The index help text files must have a name format of: xxxxxN.TXT where xxxxx = help file name prefix (5 character max) N = index field number, starting with 0. The number must correspond to the data field number. Example: To make a help file for the COALQUAL data base, 1. Make a general data base help text file called CQ.TXT. 2. Make index-specific help text files called CQn.TXT, where n corresponds to the number of the index. 3. Run GSMK_HLP.EXE, using the command line GSMK_HLP CQ COALQUAL.HLP MODIFYING THE CONFIGURATION FILE NOTE: Any editing or modifications to the .CFG file must be done using a pure ASCII text editor. DO NOT use a word-processor which creates a non-ASCII file. The only control characters which may be included in the file are carriage return (ASCII 13) and line feed (ASCII 10). Data base file names: The data base file names are specified in lines one through five of the .CFG file. You may edit them to match a new path for the data base. DO NOT PUT A DRIVE LETTER IN THE PATH. The drive letter is supplied in the GSSEARCH command line. The path\name for the GSSEARCH.HLP file is ignored, but is retained for backwards compatibility. However, the GSSEARCH.HLP file must be in the same directory that GSSEARCH.EXE is in for on-line program help. Data base title: The data base title may be edited. It is specified on line ten of the .CFG file. It is limited to 78 characters, and must end in a tilde (~) character, which acts as a stop. Index names: Index information is specified in the block of lines after the title line, starting at line 11 of the .CFG file. Index names may be edited. Index names are limited to a maximum of twelve characters, and must end in a tilde (~) character, which acts as a stop. DO NOT CHANGE ANYTHING ELSE ON THE LINE. Indexes may also be reordered or deleted. To delete an index, DELETE THE ENTIRE LINE, and change the number on line eight of the .CFG file to reflect the current number of indexes. This may be done if GSSEARCH displays a startup message noting that an index or indexes will not be used. To avoid display of the message, those indexes may be deleted from the list of indexes. To reorder the indexes, move the entire index information line within the block of index lines. DO NOT CHANGE ANYTHING ON THE LINE. Data field names: Data field information is specified in the block of lines after the index information lines. Data field names may be edited. Data fields names are limited to a maximum of ten characters, and must end in a tilde (~) character, which acts as a stop. DO NOT CHANGE ANYTHING ELSE ON THE LINE. Browse formats: If desired, users may edit one or more of the existing browse formats specified in the .CFG file. If there are fewer than five browse formats, more may be added up to a maximum of five. Browse formats are specified in the last lines of the .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 ten triads of numbers. The first number in each triad is the data field number (starting at zero) plus 1. The second number is the data field start 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. A negative number for the number of characters means that the data is to be right-justified. If you add or remove browse formats you must also change the number in line nine of the .CFG file to match the current number of formats. Command line input: Information normally input by command line may be input in the .CFG file by adding it, one item per line, after the browse format information. The input must be in the same format as described above. FORMATS OF FILES: db_name.CFG Configuration file (ASCII file) NOTE: In the example, comments are enclosed in square brackets, and are not to be included in the .CFG file. Example: \HCDN\HCDN.LV1~ [Path/names of index and data files.] \HCDN\HCDN.LV2~ [ " ] \HCDN\HCDN.LV3~ [ " ] \HCDN\HCDN.GBG~ [ " ] \HCDN\HCDN.HLP~ [Path/name of database help file. ] \HCDN\GSSEARCH.HLP~ [Path/name of GSSEARCH help file. ] 10 [# data fields. ] 6 [# indexed data fields. ] 2 [# browse formats ] * HCDN DATA 06/08/93 *~ [Data base title line plus tilde] Sta_Num ~ 3 3 1000 703 0 0 0 0 [Indexed field info lines] Sta_Name ~ 3 4 1000 600 90 54496 0 1 [ See NOTE 1 ] Region ~ 3 2 1000 21 300 170432 0 3 [ " ] Sub_Region ~ 3 2 1000 204 360 171104 0 4 [ " ] Drain_Area ~ 1 3 1000 211 420 177632 0 5 [ " ] State ~ 3 2 1000 58 930 255040 0 13 [ " ] STA_NUM ~ 8 C [Data field info lines ] STA_NAME ~ 48 C [ See NOTE 2 ] REGION ~ 51 C [ " ] SUB_REGION~ 51 C [ " ] DRAIN_AREA~ 8.2 N [ " ] NUM_YEARS ~ 3.0 N [ " ] COMMENTS ~ 500 C [ " ] STATE ~ 2 C [ " ] LATITUDE ~ 6.3 N [ " ] LONGITUDE ~ 7.3 N [ " ] -1StaNum Station Name ~ [Browse format info, see NOTE 3. ] 1 1 8 2 10 25 8 36 2 5 40 10 9 52 6 10 60 7 0 0 0 0 0 0 0 0 0 0 0 0 -2Sta_Num Station Name Area ~ 1 0 8 2 9 40 5 52 8 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 /P=C:\OUTPUT [GSSEARCH command line input] NOTE 1: Indexed field info line format example. Sta_Name ~ 3 4 1000 600 90 54496 0 1 | | | | | | | | | | | | | | | | | Data field # | | | | | | | | (starting with 0) | | | | | | | LV1 file address (unused), | | | | | | LV2 file start address, | | | | | LV3 file start address, | | | | LV2 file last block size, | | | LV2 file main block size, | | LV2 file number of address blocks | Index type (integer) 1 = numeric, 3 = character; Index name (12 chars max) plus tilde character (stop read marker) NOTE 2: Data field info line format example. DRAIN_AREA~ 8.2 N | | | | | Index type (integer) C = character, | | D = date; | | L = logic; | | M = memo, | | N,n = numeric; | Data field length[.#dec places if N] Data field name (10 chars max) plus tilde (stop read marker) NOTE 3: Browse format info. See section on modifying the .CFG file (above) for information on the browse format info lines. db_name.GBG Contains processed data base record data. Each record is preceded by a variable-length header section which is arranged as: Bytes Use Type 0 .. 1 number of fields in record; int 2 .. 3 number of 1st data field in record; int 4 .. 5 length of 1st data field in record; int 6 .. 7 number of 2nd data field in record; int 8 .. 9 length of 2nd data field in record; int etc. The header is followed by the record information. Fields are concatenated together without delimiting characters db_name.LV1 Contains address pointers for records in the GBG file. These addresses are pointed to by the LV2 file. 8 bytes per record, arranged as: Bytes Use Type 0 .. 3 Record address in unsigned long *.GBG file 4 .. 5 Word Number unsigned int 6 .. 7 Record length unsigned int db_name.LV2 Contains address information for each indexed term. 32 bytes per term, arranged as: Bytes Use Type 0 .. 23 Term name char[24] 24 .. 27 # of Addresses unsigned long in LV1 file 28 .. 31 Start Address unsigned long in LV1 file db_name.LV3 Contains address information for each block of 1000 indexed terms. 30 bytes per term, arranged as: Bytes Use Type 0 .. 24 Term name char[25] 25 Unknown byte 26 .. 29 Address of term unsigned long in LV2 file If there is only one term for the index, then the information for that term is coded. If there are less than 1000 terms for the index (i.e. less than one block of terms), then information for the first and last terms are coded. If there are more than 1000 terms for the index (i.e. more than one block of terms), then information for the first term in each block plus information for the final term for the index is coded. db_name.LV4 Contains address information for each indexed term. This file is not directly used by GSSEARCH, but is translated to ASCII by GSMK_ADR.EXE and inserted into the .CFG file following the index name. VERSIONS 4.7 94/07/15 Moved SetFile save and load functions to separate module for lower memory requirements. Added <^Enter> code to bypass Search and Display keys. Revised to use GSSEARCH.MSG for error messages. Revised to allow complete display of search terms. Added output menu bypass feature . Revised to reduce memory requirements for output. Added update of number of hits during search. Revised to allow search of date terms in YY/MM/DD format. Revised to allow use of extended .CFG file. 4.6 94/06/21 Revised to dynamically allocate all 64k arrays, saving 128k of disk space for GSSEARCH.EXE. NOTE: GSSEARCH still requires about 500k or RAM to run. Revised to conditionally read number of decimal places in numeric fields from .CFG file and save them. Revised to test for available disk space on designated output drive for .DBF and .FIX formats. Revised to output number of decimal places in numeric fields in .DBF header. Revised to replace blanks in field name with underscores in .DBF file header. Revised to allow from output. Revised to put date of db_name.GBG file into .DBF file header. Revised help function to decrease RAM requirements. Added browse display goto previous and next tagged records. Fixed bug in Edit Insert function. Fixed bug in browse display Goto Record function. Fixed bug in output of multiple .DBF files. Added code for right-justification of browse fields. Added code to remove blanks from field names for DBF output. 4.5 94/03/28 Revised to reduce RAM requirements substantially. Fixed bugs in tagged record output for very large number of hits. 4.4 94/03/18 Cleaned up mouse drive code. Revised to allow unlimited number of hits. Revised menu displays to highlight keys. Added disk space test for .DBF output for default drive. Revised to allow help text highlighting. Removed help menu messages. Revised 'Edit' function to allow inserting new search set and added mouse drive. 4.3 94/02/28 Added save and load query set file capability. 4.2 94/02/15 Substantially revised method of reading terms from .LV2 file. Fixed bug in output of .LIM format header where leading " was being dropped. Cleaned up code for cycling full record display options menus. and fixed bug which left cursor in middle of first menu. Revised to display general data base help, compatible with. GSMK_HLP v 4.0. Revised help screen colors. 4.1 93/12/15 Cleaned code for keyboard input of index name. Added code to allow typing in of field name in field selection menu. 4.0 93/12/07 Added .GRF file output capability. Added command line input from .CFG file. Revised to use Help function to show command line help info. Got rid of separate Mouse help. Revised code goes along with GSMK_HLP v 3.0. 3.5 93/11/17 Fixed bug in allowing too many searches. Decreased maximum number of search sets from 15 to 14. Added NAME HEADER output for deLimited output. Changed output of All hits to test for OutRecs == 1. Fixed bug in code for if number of fields < lines in display. Revised to use overlays for better use of memory. Added tests for disk space. 3.4 93/10/04 Increased number of help lines to 512. Expanded help panel to go to bottom of screen. 3.3 93/09/14 Expanded help display box. 3.1, 3.2 Unreleased versions 3.0 93/08/24 Added mouse drive to search set build and edit function. Revised to allow mouse driven pop-up menu. Added enhanced mouse drive to help display. Added message for lack of help file. 2.5 93/03/18 Fixed bug in AdjSearch. Modified AdjSearch to allow 32000 hits. Added messages during search. 2.4 93/03/03 Revised to allow black & white display for sight-impaired users. 2.2 93/02/12 Revised to allow toggle of display to main window. Added code to allow typed input of index name. Added elevator to side of help display box. Modified to write help display to video page 1, and to allow toggle to page 0. 2.0 92/12/10 Removed adjacency search from menu and put into term selection function. Changed range search keys to , , , >. Expanded help display box. Changed search term display length. Added code to force index selection if adjacency searching. Added up and down arrows to side of help display box. Made Year Table capability generic. Revised search set build function to save last logical operator, index, and search term chosen. Added input of index from query editing function. Added CtrlUp and CtrlDn to index and term selection. Added tests for compatible key input for term types. Revised logic selection function to use standard menu function. Changed number of help lines possible to 500. Added mouse capability, help. Revised to use standard pop-up menu function. Revised main loop. Added up and down arrows on index, term, browse and full record display boxes. Added mouse help info. 1.0 91/10/10