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] <ENTER>

           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 <ENTER>           



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 <F9>.
            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 <Esc> 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 <END> 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 <TAB>, <SHIFT TAB>, <ALT <>,
              <ALT >>.
            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, <F1> 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