GSSTK.HLP 2000/09/05 GSSTK is an update of GSSEARCH, rewritten using C and Tcl/TK (Tool Command Language/Tool Kit) to run on a variety of platforms and operating systems. The C executable provides the "nuts and bolts" of the application, doing the searching and formatting of the data, while the Tcl/Tk part provides the graphical user interface (GUI). To run, the Tcl/Tk interpreter (version 8.0 or newer) must be installed on the user's system, and the C executable must be compiled for the user's operating system. The Tcl/Tk interpreter software is available at http://www.scriptics.com GSSTK is fully backwards-compatible with existing GSSEARCH databases. GSSTK works much like GSSEARCH did, so someone familiar with the old software should have no trouble using GSSTK. However, GSSTK incorporates some major improvements. -- Databases may be opened or closed from within the GSSTK program; -- Browse record format scrolling is continuous; -- Multiple records may be displayed simultaneously; -- The record data may have hot links to image files (.gif format) and .txt ASCII text files; -- The record data may have hot links to html files or URLs; -- Linked text files may have hot links to other image and text files, or to html files or URLs; -- A "Find" text search function has been added to the record and help displays; -- Functions to move between marked records have been added to the record display; -- Balloon help for all functional widgets has been added; -- The browse record display features resizable columns; -- Fonts and font sizes for various windows are user-selectable; Software Bug Reporting Please report software bugs to Kim Buttleman via email at kbuttlem@usgs.gov If a software error should occur, an error window will be displayed. Click on the [Stack Trace] button, and copy the error message into the email message. Please include as much information as possible regarding the circumstances of the error. ----------------------- GENERAL INFORMATION --------------------------- For all windows except dialog boxes, moving the mouse cursor over an object will display a brief description of that object. In addition, in the main window, a brief description of the menu items will be displayed in the footer as the mouse cursor traverses the menus. In all windows and dialog boxes, software help may be displayed via the [Help] button. Where appropriate, a menu allowing the choice of database help may also be displayed this way. NOTE: The help menu (database help or program help) may be bypassed, where appropriate. displays program help displays database help BUTTON CONVENTIONS Buttons will be designated with the button name or function in square brackets, i.e. [Output] KEYBOARD CONVENTIONS Single keys are enclosed in angle brackets, i.e. . The key is signified by the ^ (caret) symbol. The key is signified by the @ (at) symbol. Combinations keys (i.e. and ) are designated by the caret or 'at' symbol and the key, all enclosed in angle brackets, i.e. <^Left>, and means to hit both keys at the same time. Arrow keys are designated as , , , and . MOUSE CONVENTIONS = (Left mouse button click) Emulates : Select the option; = (Right mouse button click) Emulates : Abort the operation. <2xLMouse> = Left mouse button doubleclick. Picking an option from the list of on-screen options: To execute one of the on-screen options, move the mouse cursor over the desired option in the screen prompt area, and click . Moving the highlight: To move the highlight in any of the list boxes (indexes, search terms, data fields, or browse list), move the mouse cursor to the desired list item and click . A double click of the left button emulates on the highlighted selection. Scrolling: To scroll one of the list boxes or text displays, move the mouse to the up or down arrow on the scrollbar and click or hold down . You can emulate the and keys by placing the mouse cursor on the right side of the box, above or below the "elevator", and click or hold down . All list boxes also have [Home] and [End] buttons at top and bottom of the scrollbars. COMMAND LINE OPTIONS: (See GSSTK.DOC for more information) path/dbname.cfg Configuration file for database. Use complete path, including drive letter for Windows. /F=c Delimited output data field separator character. c = ASCII character; default = , (Comma) /D=c Delimited output character data delimiting character . c = ASCII character; default = " (Double quotes) /P=outpath Default path for .ASC, .FIX, .LIM, .DBF output files. /G=grfpath Default path for .GRF output files (if available). /L=x Lat/Lon conversion flag SUM for MAPPER software .GRF file output (if available). MAPPER requires signed decimal latitudes and longitudes, and presumes S and W are negative. Default is no conversion. x = 1 Reverse sign on latitudes. = 2 Reverse sign on longitudes. = 4 Convert DDMMSS latitude and DDDMMSS longitude to decimal latitude and longitude. Example: /L=6 will convert lat and lons from DDDMMSS format to decimal and will reverse sign of longitudes. (i.e. longitude 1024500 to -102.7500.) 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. ------------------- MAIN WINDOW & SEARCH SET DISPLAY -------------------- This window displays the query criteria and provides database search and display options via pull-down menus and menu buttons. From this screen you can select any of the main menu choices listed at the top of the window, or from the buttons on the button bar. Search Procedures A search is done by building a query from one or more search sets, connecting each set to the next with a logical operator. Each set is specified by clicking on the [Add] button. A sequence of steps allows the user to build a search set. This may be repeated up to fifteen times to construct the query. The search sets are displayed in the center panel of the screen. The table shows the logical operator, index, the term(s) selected, and the number of occurrences of the term(s). The logic specified by the operators is performed in sequence, with the results of previous steps being the input to subsequent steps in the logic sequence. Expert search mode may also be used to build complex searches. Expert mode is selected from the Options|Search Mode menu. Next, [Search] is selected to execute the search and retrieve all matching records, or "hits". You may select [Browse] to view retreived records. Within the BROWSE window, you may browse the selected records in a summary display or look at individual records in full format. Records may be output to file from within the BROWSE or FULL RECORD windows, by clicking on the [Output] button. [Edit] allows the user to edit the currently displayed query, and [Clear] will delete all search sets. Menus File Open database Select/Open a GSSEARCH database. Close database Close current GSSEARCH database Quit Exit GSSEARCH Query Build Build a query. Execute Use the existing query criteria to search the database. Edit Edit the existing query. Clear Clear the existing query. Set file >> Load or save search set to a .SET file. Load Load search set .SET file. Save Save search set to a .SET file. Window Query build Display Query window. Browse Display Browse window. Records >> Full record display windows. Link files >> Linked file windows. Options Fonts Select font options. Search Mode Select Normal or Expert search modes. Balloons >> Balloon Tip display options. Show Balloons Checkbox for balloon display Set balloon delay Set balloon display delay Build Dialog >> Select Build Dialog configuration Configuration 1 Select config 1 (Wide) Configuration 2 Select config 2 (Cluster). Browse Window Paging Set maximum number of hits for sorting Help Database Display database help. Software Display software help. About Display info about GSSEARCH Tcl/Tk -------------------- QUERY BUILD WINDOW ---------------------------- LOGICAL OPERATOR SELECTION A drop-down listbox allows selection of an operator which determines how this search condition is related to the previous condition. The operators are interpeted using boolean logic. The following rules apply: AND - finds any record which meets this condition AND the previous condition; the result is an intersection of the two sets. OR - finds any record which meets this condition OR the previous condition; the result is a union of the two sets. NOT - finds any record in the previous set which does NOT meet this condition. NOTE: In 'Normal' search mode, the logical operators are processed in sequential order. There is no other operator precedence. Normal or Expert modes are selected from the Options|Search Mode menu. INDEX SELECTION A drop-down listbox of every field that is indexed, and therefore searchable, allows selection of an index. Index Searching: All indexes may not appear in the listbox at once. Scroll through the index display with the mouse or -- Move the highlight bar up. -- Move the highlight bar down. Speed Searching: You may also speed the search for the desired index by typing in the characters in the index entry box. As characters are typed, the FIRST index in the listbox that matches the current input characters will be highlighted. Note that the list of indexes does not have to be in alphanumeric order. will delete the last character. will delete the entry. Any of the highlight motion keys above will erase the input characters. Index Selection: -- Select the highlighted index and go to the SEARCH TERM window. -- Output to file a list of all search terms for the highlighted index. SEARCH TERM SELECTION Entry boxes and drop-down listboxes allow selection of a search term or range of terms from the previously selected index. The term listbox(es) contain every unique term in the chosen index. The left side of the the window displays the term while the right side displays the number of occurrences of that term. TERM Searching: All search terms may not appear in the listbox at once. Scroll through the term display with the mouse or -- Move the highlight bar up. -- Move the highlight bar down. Speed Searching: You may also speed the search for the desired term by entering the term in the term entry box. As characters are typed, terms appear in the listbox beginning with the term that matches the characters entered. will remove the last character. will delete the entry. Any of the highlight motion keys above will erase the input characters. TERM Selection: Select the highlighted term. RANGE Searching: Range searches may be done in one of three ways: 1) Select all terms less than or equal to a term by selecting the term and then clicking the [Range: Less than or equal to] button. 2) Select all terms greater than or equal to a term by selecting the term and then clicking the [Range: Greater than or equal to] button. 3) Select a range of terms by selecting the first term, then clicking the [Range: All terms between Term 1 and Term 2] button, then selecting the second term. ADJACENCY or PROXIMITY Searching: Select the first search term. Click on the [Proximity Search] button. Select the second term. Accept or edit the distance criterion. Click on the [Accept] button. NOTE: Adjacency searching is valid only if the data field searched has more than one term in each record. NOTE: Proximity values are limited to 1 .. 10. "AND" searching is more effective for distances greater that this. Other: -- Output to file a list of all search terms for the highlighted index. SEARCH SET ACCEPTANCE Click the [Add] button to accept the query. You may alter any part of the query prior to accepting it. Add another search set or hit [DONE] to quit the Query Build window. ------------------- EXPERT MODE SEARCH INFORMATION ------------------------- Expert search mode permits very complex search logic to be performed. In expert search mode, the user selects a number of "hit sets", each of which is designated by a number. These sets are then connected in a query, using parentheses, square brackets, and curly brackets. This allows more complex logic than the normal mode search. Expert search mode may be implemented via the Options|Search Mode|Expert menu. Queries are made be first specifying a number of "hit sets". These are not connected by logical operators (as in normal search mode), but are referred to by set numbers, starting with 1. These sets are then connected in a logical sequence using brackets and logical operators. BRACKETS: Queries may be constructed using parentheses, square brackets, and curly braces. There is no prioritizing of brackets, but each left bracket must be matched by a right bracket. The software will test to make sure that the brackets are balanced. Each bracketed logic sequence must have two sets separated by a logical operator. The software processes the query recursively, processing the innermost bracketed logic sequences first, and then using the results of those searches as inputs to the outer sequences. Placing the cursor on a bracket will blink the matching bracket. LOGIC OPERATORS: Logical operators are "AND", "OR", and "NOT". Both upper and lower case are acceptable. The operators may be abbreviated using the following symbols: & = AND | = OR ! = NOT "AND" and "OR" may be used in a bracket more than once. See examples 2 and 4. However, they may not be mixed, i.e. [1 or 2 and 3]. "NOT" may not be used in this manner. EXAMPLES: Example 1: [(1 or 2) and (3 not 4)] Example 2: [(1 or 2 or 3) and 4] Example 3: [(1 or 2) and {3 not (4 OR 5)}] Example 4: [1 not (2 and 3 and 4)] Example 5: [(1 | 2) & {3 ! (4 | 5)}] Example 3, alternate notation. NOTES: The software ignores spaces when processing the query. However, they generally make the query more readable. During processing, the software creates working files using the file name template TMPnnnnn.$$$, where nnnnn is an integer. These files are normally deleted upon exit from the GSSEARCH program, but may be left on your hard disk if you break out of the program. If search sets are defined in expert search mode and the mode is then changed to normal search mode, the sets will be connected with "OR" logical operators. -------------------------- SEARCH EDIT ---------------------------------- Previously defined search sets may be edited or deleted, or new ones inserted into the query set. The edit function is implemented via the [Edit] button on the main window. The search set to be edited or deleted is first selected by highlighting the set. Then choose from the edit dialog the action desired. [Edit] allows editing of the highlighted set. If the set is to be edited, the logic operator selection window will be displayed, with the original logic operator highlighted. You may accept the original logical operator or select a new one. The index selection window will then be displayed, with the original index highlighted. Accept the original index or select a new one. The search term selection window is then displayed. If the original index was accepted, the original search term will be highlighted. If a new index was selected the first search terms will be highlighted. Accept the original search term (if applicable) or select a new one. Range searches may also be altered in this way. [Delete] will delete the highlighted set. If the set is deleted, the sets below it will be moved up. [Insert] allows insertion of a new set ABOVE the highlighted set. --------------------------- BROWSE WINDOW ------------------------------- This screen lists a summary line from each record in the retrieved set. The summary line consists of a set of user-selectable fields as specified in the database .CFG file. See GSSTK.DOC for information on how to specify the browse formats. Records are displayed as resizable columns of data. Each data column contains up to 100 characters of data from the record's data field, and the columns may be resized by grabbing the edge of the column label with the mouse and moving it. Browse List Paging Threshold: The browse display list is normally treated as a continuous list of record summaries. For performance considerations, when the number of hits exceeds a user-specified threshold (default = 1000), the display software segments the list into pages. Treating the browse list as pages prevents record sorting (see below.) The user may specify the threshold in the Options|Browse_Window_Paging menu. Browse Record Sorting: The browse records may also be sorted by data column, if the number of hits is less than the Paging Threshold. Click on the column header to sort the data. The sort type (ascending or descending) is toggled with each sort of the column. NOTE: The maximum record size is 64k bytes. Scrolling: -- Move the highlight bar up. -- Move the highlight bar down. Full Record Display: -- Display FULL RECORD window for the highlighted record. Multiple full record windows may be displayed. Marked Records: Records may be marked for output or for full record viewing. Records are marked by clicking on the listbox to the left of the browse display. clicking toggles the mark. -- Mark the highlighted record. <^Ins> -- Mark all records. -- Unmark the highlighted record. <^Del> -- Unmark all records. Button bar information: [Help] Display help menu [Output] Display the OUTPUT OPTIONS dialog. Marked records may be output by selecting them in the record mark listbox, or by the following keys. See below for further information. [LINK=#615;] [GoTo] Go to the specified record. Buttons for scrolling to the first, previous, next, or last marked records are on the button bar. <^Home> Go to first marked record <^PgUp> Go to previous marked record <^PgDn> Go to next marked record <^End> Go to last marked record Browse Format Selection: Up to five browse formats may be defined in the configuration process. A button for each format will be displayed on the button bar. The different browse formats (if available) may be invoked by clicking on buttons [1] to [5] or by striking the appropriate key <1> .. <5>. ----------------------- FULL RECORD WINDOW ------------------------------ All fields which are present in the current record are listed down the screen. The text may not be edited, but it may be selected and copied to the computer clipboard or another editable text item. NOTE: The maximum number of lines displayable is 1024. The maximum record size is 64k bytes. Copying text: The text may not be edited, but it may be selected and copied to the computer clipboard or another editable text item. Highlight the text using the mouse, then hit <^C> to copy it to the system clipboard. Hit <^V> to paste it from the clipboard to editable text. Scrolling: All fields may not appear on the screen at once. Scroll the record with the mouse or -- Move the display up. -- Move the display down. Shifting: If any of the displayed lines extends beyond the right side of the screen, shift the record display with the mouse or -- Move the display 1 character -- Move the display 8 characters <^Left> <^Right> -- Move the display 1 panel -- Return display to original [Help] Display help menu [Output] Display the OUTPUT OPTIONS dialog. Output is limited to the currently displayed record. Multiple records may be output from within the BROWSE WINDOW. See below for further information. [LINK=#615;] [Find] Search for text in the record. [GoTo] Go to the specified record. [Display] -- Display the DISPLAY OPTIONS dialog. See below for further information. [LINK=#778;] Record Display Buttons: Allow display of first, previous, next and last records. The existing record window will be overwritten. -- Go to first record. -- Go to previous record. -- Go to next record. -- Go to last record. Marked Record Display Buttons: Allow display of first, previous, next and last marked records. The existing record window will be overwritten. <^Home> -- Go to first marked record <^PgUp> -- Go to previous marked record <^PgDn> -- Go to next marked record <^End> -- Go to last marked record -- Mark the displayed record. -- Unmark the displayed record. ---------------------------- OUTPUT OPTIONS ----------------------------- This dialog allows output of record data to disk file. The output dialog allows a variety of options. Selection of an option in one box may enable or disable appropriate choices in other boxes. Output from the Full Record Display screen is limited to the currently displayed record. However, individual records may be tagged (and untagged) for output from the Browse Display with and . The output files are given a default path/name, which the user may edit. OUTPUT OPTIONS DIALOG SUMMARY RECORD options (Available from Browse display only.) All Records -- Output all the currently selected records. Tagged Records -- Output the currently tagged records. FORMAT options ASCII -- Output record data as ASCII data. Record data are output line-by-line as data field name followed by field data. Null data fields may be retained or excluded. Records are separated by two blank lines. Default file name extension = .ASC Tagged Text -- Output record data as Tagged (Fielded) ASCII data. Similar to ASCII format but data field names are enclosed within curly brackets, i.e. { and }. Record data are output line-by-line as data field name followed by field data. Null data fields may be retained or excluded. Records are separated by two blank lines. Default file name extension = .TAG Format is for input to GSBUILD software. See GSBUILD.DOC for information on building databases starting with tagged text file. Fixed length -- Output record data in fixed length format. No data field names are output. Data fields are output in the order that they appear in the CFG file. NOTE: This option is disabled if the data fields are out of order. Data field lengths are those in the database configuration file. Data fields are not separated. Records are separated by carriage return/line feed combination. Memo type data fields are not output. A field of ten blanks is output instead. Default file name extension = .FIX Delimited -- Output record data in delimited format. Data field name header optional (See menu 6). Data fields are output in the order that they appear in the CFG file. NOTE: This option is disabled if the data fields are out of order. Data fields are separated by separator character. (default = comma). NOTE: The data field separator character may be set using the command line option /F=c where c is the separator character. Control characters (i.e. TAB) may be used. Character field data are enclosed by a delimiting character. (default = "). NOTE: The delimiting character may be set using the command line option /D=c where c is the delimiting character. Numeric fields are not set off by the delimiting character. Data field lengths are truncated if blank. Records are separated by carriage return/line feed combination, with NO data field separator character at the end of the last field in the record. Default file name extension = .LIM DBase -- Output record data in DBase format. Data fields are output in the order that they appear in the CFG file. NOTE: This option is disabled if the data fields are out of order. Default file name extension = .DBF .DBT for memo fields NOTE: The maximum number of data fields is 512. NOTE: If the .CFG file does not contain numeric field decimal place information, decimal places will not be put into the DBF file header. NOTE: Blanks will be removed from field names. NOTE: 'E' and 'n' data fields will be converted to 'C'. GRF for GIV -- Output record location in .GRF file format for plotting by MAPPER.EXE. Default file name extension = .GRF NOTE: This format is available only if the database contains fields named LAT or LATITUDE and LON or LONG or LONGITUDE. Latitude and longitude values should be in decimal degrees with S lat and W lon negative. See GSSEARCH.DOC for information on format conversions available by command line input. NULL FIELDS options (For ASCII and Tagged Text formats only.) Exclude -- Exclude null (empty) data fields from output. Retain -- Keep null fields in output. HEADER OUTPUT options (For deLimited format only.) No header -- Do not output header of data field names. Header -- Output header of data field names. Names are delimited by double quotes and separated by commas. The header is ended with a carriage return/line feed combination, with NO COMMA after the last field name. FIELD DELIMITER entry box and TEXT DELIMITER entry box (For deLimited format only.) Allow user to override the default values for field delimiters. Field delimiter -- Character used to delimit non-text data fields. Default = comma Text delimiter -- Character used to delimit text data fields. Default = double quotecomma DATA FIELDS options (For ASCII, Tagged Text, Fixed, deLimited, and DBase formats) All -- Output all data fields. Selected -- Output a selected set of data fields. SELECTION listbox (If Selected fields option is chosen) Choose the data fields to be output. Select multiple fields with . Select a sequence of fields by on the sequence start field, then on the end field. ---------------------------- DISPLAY OPTIONS ---------------------------- This dialog allows control of record data display options. Selection of an option in one box may enable or disable appropriate choices in other boxes. Options set in the DISPLAY DIALOG will effect the currently displayed record, and not existing record windows. However, any new record windows which are displayed will use the options set in the dialog. Existing record windows may be redisplayed with the new options by going to that window, clicking the [Display] button, then the [Apply] button. DISPLAY OPTIONS DIALOG SUMMARY FIELD SELECTION options Display ALL fields. Display SELECTED fields. HIGHLIGHTING options Highlight search term in ALL fields. Highlight search term in SEARCH field. Turn highlight OFF. SPACING options Turn on display DOUBLE spacing. Turn on display SINGLE spacing. NULL FIELD options. EXCLUDE null fields from display. RETAIN null fields in display. WORD WRAP options. WRAP the display. DON'T WRAP the display. COLOR options Select foreground/background colors for Highlighting of search term; Text find; Text and image hot links. DATA FIELDS options Display ALL data fields. Display a SELECTED set of data fields. SELECTION listbox (If Selected fields option is chosen) Choose the data fields to be displayed. Select multiple fields with . Select a sequence of fields by on the sequence start field, then on the end field.