This program, like s.db.rim, is actually a marriage of the GRASS environment and the programmer's interface library of the relational data base management program RIM distributed publically by the University of Washington Academic Computing Services. Your system must have a FORTRAN 77 compiler to use this program.
Each vector data base is composed of multi-field records (rows or tuples, in DBMS jargon). Each field and its position in the record form is defined via input to the .make command when a data base is originally defined. It is possible to add new fields or change the length of existing fields after data has been loaded, however this is not straightforward; deleting of fields is also possible, but requires even more experience and knowledge. The user needs to carefully design the data base fields and form (layout) and check the operation with a few pieces of test data before loading data for a large number of records.
One significant difference between v.db.rim and s.db.rim is that v.db.rim needs access to the original vector maps that data were imported from to successfully complete some commands. To keep track of which records were imported from which vector maps a new "table" has been added that keeps information about the reference vector maps. This table is called "Referencemaps" in the RIM data base. The v.db.rim commands .read_vect, .map and .maps allow the user to view and update this table. The .vector_map command, which creates a new GRASS binary vector file, requires that the reference vector maps for the database be accessible. If a reference map is not accessible, any vectors represented by the data base records that were generated from that vector map will not be transferred to a new vector map. Reference vector maps may be in any mapset in the current SEARCH_PATH.
The commands are given alphabetically here for easy reference. The .make command is required to create a data base. Abbreviations down to the string shown in ( ) are accepted; this is primarily for those giving v.db.rim commands from a terminal, but abbreviations may also be used in batch files.
Each command is introduced with an input record (line) which starts with a period and is followed by one of the words shown below; for some commands the command line also contains one or more required or optional parameters. Additional or optional input instructions/data for a command is supplied on successive lines; a .end line is needed by some commands to signify the end of these lines.
"Alphabetical Command Summary"
Example: .add seq_num 204 north 4690673.30 east 601410.00 map_num 1 vect_type L reference Jones (1987) .end
To reload your data base from the backup file (normally not necessary):
GRASS 4> cd $LOCATION/rim/vect #right directory
GRASS 4> rm db_name.rimdb* #remove data base
GRASS 4> rim #run RIM manually
RIM> input "path/file" #RIM rebuilds data base from data
written by .backup
RIM> exit
If the "-l" flag (for "list") is given, the sequence number field is omitted and the specified field values are changed in all records currently selected by .find and/or .query.
A backup of the data base or copies of the data base files are the ways to protect your valuable data. The following command sequence will delete all the records currently on v.db.rim's query list (the result of the last .query or .find command), after asking for approval.
.delete .end
The single required line following the .find line gives the program the necessary target information. The following examples show the possibilities.
find> 602793.90 4379010.00will find the one record nearest these coordinates and store it, append it or delete it on the internal query list.
find> 619840 4599000 10will find the 10 records (or fewer, if there are not that many) closest to the given location.
find> record 132 10will find the 10 records closest to the location (label point) for record 132 in the data base (including record 132). If record 132 does not exist, no action is taken.
find> distance from 472910.06 5732001.0 5000will find all records within 5000 (meters in UTM coordinates) of the target location.
find> distance from record 16 -2500will find all records greater than 2500 (meters) from the location of record 16.
Notes for .find:
1. All records found by each .find are stored on the query list in order of proximity to the target location (sorted by distance from target).
2. The number of records found is automatically printed to the active output device/file.
3. If mask is specified, the effective region is automatically set to the current region (because the GRASS mask is only defined for the current region).
4. Region and mask filtering uses the current resolution for the region to test if a point falls within a cell.
5. In the last two examples the string "distance from" must be exactly matched. Also, the word "record" must be exactly matched.
6. If the "distance from" radius is given as a negative value, points outside the target circle are selected; whereas, if a positive value is given, points inside the circle are selected.
7. The current region may be changed with !g.region or !d.zoom prior to doing a .find, and the mask may be set or removed with a variety of GRASS commands.
8. The "find>" prompt is given only when input is from a terminal.
9. The "distance" between the target location and a record for a line or an area is actually the distance between the target location and the representative point that is stored in the data base. This can lead to unexpected results when the representative point (label point) for a line or area is not near the "center" of the feature.
1) The fixed text part of the screen layout. 2) The positions, types, and lengths of data fields.
Five fields must always exist in a data base; each of these field types may only occur once in a data base layout:
1) Type 's' Sequence number field (a unique integer for each record). 2) Type 'x' Easting coordinate of the representative point (a double float). 3) Type 'y' Northing coordinate of the representative point (a double float). 4) Type 'v' Vector type field (a text field). 5) Type 'm' Reference Map field (an integer).The other field types, which may occur in any combination and order, are:
6) type 'i' An integer field.
7) type 'f' A double precision float field.
(always 2 decimal places used for output)
8) type 't' A text field.
Each of the fields can be positioned anywhere within the screen
layout, which has a limit of 19 lines by 80 columns. A maximum of 70
fields may be defined within this space. A field is specified in the
screen layout by a tilde (~), a field type character, a field name and
enough trailing tildes to fill out the desired field length.
Each line following the .make command is taken to define a line of the screen layout until a .end is reached. If a mistake is made on any of the input lines, the .make will fail. The .make information may be prepared in advance as a text file (this facilitates fixing mistakes) and the .input command can be used to read in this file. An example text file for a data base screen layout follows, with some explanatory notes and restrictions.
.make
Hydrology Vector Database
=========================
Record #: ~sSeqnum~ Feature Name: ~tName~~~~~~~~~~~~
Vector type: ~vVtype Reference Map: ~mRefMap~
North: ~yNorth~~~~~ East: ~xEast~~~~~~
Updated: ~tUpdate_Date~~~~~~~
Comments:
~tComments.1~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~tComments.2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~tComments.3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.end
Notes:
1) Any text not preceded by a tilde (~) character is taken to be part of the constant or fixed text portion of the form.
2) A field definition begins with a tilde (~) character immediately followed by a single character which indicates the data type of the field (s,x,y,v,m,i,f or t). Immediately following the data type character is the field name of 1 to 16 characters. Field names can be composed of any characters from the following set: [A-Z,a-z,_,0-9]; the RIM program and library do not distinguish upper and lower case in field names, so you should avoid making names which differ only in case. Field names may not begin with a numeral [0-9]. The rest of the field length is padded with tilde (~) characters to the length desired.
3) The minimum field width is three characters; e.g., "~tA". Be sure field widths for all fields are wide enough for the values and strings you expect to store there; e.g., UTM northings require at least 11 spaces.
4) For text fields it is possible to continue a field across more than one line. This is done by appending a .1 to the field name forming first portion of this "split field", a .2 for the second portion, etc. This text field splitting affects how information is organized for input and output; the composite text string is concatenated (unused portions of fields are retained as spaces) and treated as a unit for storage and queries to the data base.
Finally, to delete a map from the reference maps table, use the '-d' option followed by the map number (map_id). The map information for the given map number will be displayed and the user will be asked to confirm the deletion with a 'y'. Enter a 'n' (for no) if you do not want to delete that reference map.
Remember, that if you delete a reference map for which there are still records in the data base, you cannot make a new vector map (using the .vector_map command) that includes those records unless you put that number and vector map name back in the reference map table.
.output | grep "easting" | wc -l > /tmp/my_countA pipe is closed whenever the .output command is given again, or on a .exit command.
The optional .query command line parameters cause records whose representative points are not in the region (-w) and/or mask (-m) to be rejected, so these conditions need not be tested in the "where clause". See .find for a full explanation of the command line options.
After the query command line, any number of lines (each no more than 80 characters) may be entered to define the SQL "where" clause. A .end line is required to finish the request and begin data retrieval. See examples below.
The "distance from" clause may also be used as an additional selection criteria exactly as described in the examples and notes for .find. It must be entered as a separate line to the query prompt.
The retrieved records may be printed at time of retrieval, rather than after the completion of the query command by including a .print (.p) line with the same options for print format as in the .print command (see above); e.g. .p -a to output in the "list add" format. The .print clause must be entered as a separate line to the query prompt. This feature is most useful when working with very large data bases where retreval time is significant. See example 2 below.
Example 1
query> where density < 20 and (date = "10/14/89" query> or county eq "San Marcos") query> .endExample 2
query> where east <600000 and name like "*Jones*" query> distance from record 12 3000 query> .print -a query> .endExample 3
query>.endThe where and distance from clauses are each optional. If both are omitted, only the mask and region on the .query command line restrict the search; if mask and region are also omitted, all records will be retrieved (Example 3). When querying for records the where clause is processed first, the current region and mask tested (if requested), then the distance from clause is applied; a record must pass all tests to be put on the internal query list (or appended or deleted) for output by other commands.
Notes: (Also see Notes for .find)
1. The retrieved records are stored on the internal query list in the order returned from the data base by RIM, not necessarily in sequence number order or the order the data was loaded. A "distance from" clause results in a final sorting by proximity to the target.
2. See the RIM User's Manual and the s.db.rim manual page for additional information on the "where clause" in the "select" command, especially the quotes required for matching character string (text) fields, and the allowed comparison operators. (These are also described in SECTION TWO of this manual entry.)
3. In the example where clauses above, "density", "date", "county", east", and "name" are field names (column names in RIM) defined when the user initially makes the data base.
4. Each .query or .find resets the internal query list, unless the append or delete options are used. In no case is a record allowed to be duplicated on the query list.
Once the records have been loaded by .read_vect, use .change to add data to other fields for those records.
Note: Only labeled areas, lines and points are imported from the vector map.
A comment line is inserted in the site_list file with the current date and time and the name of the data base producing the site locations. The format used for each site is:
easting|northing|#number or comment
If the optional attribute_field parameter is provided, the areas and lines in the new vector map will be labeled from the given integer (i, m or s type) field value for each record. You may supply a fixed integer value (such as 1, 908, -7, etc.) instead of a field name; each line written to the new map will be given this constant attribute/label.
If the optional text_field is provided, it will be used to build a category description file (dig_cats file) for the vector map. Instead of a field name, a constant text string of up to 100 characters may be given, if enclosed in single or double quotes; this string is used as the category description for each line written to the new vector file.
The header of the new binary vector file will contain the current date and indicate that v.db.rim was used to create the vector map.
The topology information (the dig_plus file) is not automatically built for the new vector map and the user must run support.vect to do so before v.digit can be used to edit the vector map or some other programs can be used. The vector map can immediately be displayed, from within v.db.rim by issuing the following command (assuming you have a graphics monitor selected):
!d.vect file_name c=color
v.db.rim MAIN MENU Version 1.4
Data base <rivers> in mapset <kittco> open. 325 records.
1 Open a data base
2 List available vector data bases
-------- Retrieve/Output Site Records (8 currently) --
3 Find records in proximity to a Target point
4 Query to select records (SQL)
5 Show selected records on Terminal
6 Display maps/selected vectors on graphics terminal
7 Output selected records to Printer or File
8 Create vector/site maps from selected records
------------ Add/Edit Site Records ----------
9 View a single record
10 Add a record
11 Change a record
12 Delete a single record or all selected records
------- Other functions -- Shell Command -- Exit ----------
13 Make a new data base & Management Functions
14 Execute a shell command
0 Done -- Exit from v.db.rim
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR <Ctrl-C> TO EXIT THIS PROGRAM)
1. Open a data base. If a data base is already open, it is closed
before the requested one is opened. Only data bases in the user's
current mapset may be modified; others are opened in read-only mode; this
will be indicated on line 2 of the menu.
2. List available data bases. For each mapset in the current GRASS mapset search path, the names of the existing vector data bases are listed.
3. "Find" records in the data base relative to a specified target location. This is used to select records based on proximity to the target and, optionally, records within the current region and, optionally, records falling in active cells within the current GRASS mask. The label point coordinates are used for these spatial tests. Two modes of targeting are provided: the N records closest to the target, and all records within (or outside) a circle of specified radius from the target. The FIND/QUERY TARGET MENU discussed below accepts region/mask/target specifications from the user. The selected records are then displayed one at a time until CTRL-C is entered; then other operations, choices 5-8, can be done with these records. The line on the menu between 2 and 3 shows the number of records currently selected by choices 3 or 4.
4. "Query" records in the data base using an SQL-like "where clause," including specifications for region/mask/target (circle only) as in 3, above; see FIND/QUERY TARGET MENU section below. The where clause can test for ranges or matches for numeric data base fields, or matches on full strings or substrings for text fields. The selected records are then displayed one at a time until CTRL-C is entered; then other operations, choices 5-8, can be done with these records. This clause is entered on a QUERY COMMAND MENU described below.
The where clause may use parentheses ( ) to control the order of comparisons. Field names are not case sensitive within where clauses. The following comparison operators are valid for all types of fields:
eq or = ne or <>
ge or >= le or <=
gt or > lt or <
String comparisons are case sensitive and are done character by
character. Substrings comparisons may be done with the "like" operator
as in:
where name like "*Jones*"
Note that the string being tested against the name field for each
record is in quotes (single or double) and that wild card comparisons
can be done in the standard way with '*' and '?' characters.
Logical comparisons may also be combined with those operators above. The permitted logical operators are:
and or not
The following complex example should be examined. The line breaks can
occur between any tokens (words, values, operators), except within
quoted strings.
where (name like "*Jones*" or name = "Smith")
and ( ( site < 300 and not (site = 251 or site eq 15) )
or east < 601000 )
5. This choice will display the records resulting from the last
find/query one at a time on the terminal. Use ESC or enter a number
to display another record and CTRL-C to end the display.
6. If a graphics monitor is active, the selected vectors will be displayed. The user may choose to erase the screen; display cell, vector, and/or site maps; and/or display the selected vectors from the data base; these maps are requested through the following interactive screen. Just enter ESC to skip this step. If no data base vectors are currently selected, that section of the menu will not appear; but the menu can still be used to display the other types of maps.
SELECTION MENU FOR ITEMS TO DISPLAY
Enter cell and/or vector map names, if desired
______________ Cell file to display
______________ Vector file to display in color: _________
______________ Site list to display
Dpoints with: size=3_ type=box____ color=white____
_ Display currently selected vectors (enter x)
Dvect red______
_ Erase graphics screen (enter x)
Derase black____
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR <Ctrl-C> TO CANCEL)
7. This selection results in a screen prompting for the name of the
file to output the selected records to, and for optional formatting
selection. If the file name is lp, the site records are sent to the
printer. The optional formatting choices are for export of data in list
and add formats; see the .print description in SECTION ONE of this
manual page for information and examples.
8. Using this choice you can create a new GRASS vector map consisting of the vectors for the currently selected records, and/or a site list consisting of the representative points (label points) for the currently selected records, in your current mapset. A short menu prompts for the map names and other information.
If a vector map name is given you can choose an integer field (i, s, or m types), or a fixed value, to write as the label value for each vector in the dig_att file for the new map. You may also specify a field name (any type), or a fixed text string in single or double quotes, to write as the category description in the dig_cats file for the new map.
If you give a site list name, you can specify the name of a field (or fixed text string in quotes) to be used for the "#comment" in the site list (the record number is the default field). The current date and time, and the names of the mapset and data base in use are entered as an information line in the site_list file. Note that you can create a new site list or append to an existing site list, or both.
A variety of cell maps can be produced from a v.db.rim data base by creating new vector files then using the v.to.rast program, and by writing site_lists with different fields as "comments" then converting the site_lists to cell maps with s.menu.
9. Choices 9-12 operate on only a single record and do not use or modify the internal list of records selected by find/query (choices 3 or 4). Choice 9 is the way to view a single record, selected by record number. After viewing, ESC will allow entry of another site number and CTRL-C will exit to the main menu.
10. Use this selection to add a new record to the data base. (A new record is one whose number does not currently exist in the open data base.) After making this selection, the data base layout will be displayed and you should enter the available information appropriate to each field; the only required entry is the site (record) number field. If values for numeric fields are not entered, zero values will be stored. Unused portions of text fields are stored as strings of spaces.
11. After making this selection and specifying the record number to change field information for, the data is entered as for choice 10, except that the record number cannot be changed. (The command version of the program has provision for making bulk changes after a find or query; see .change.)
12. To delete a single record, enter its number when requested. All records chosen by the last find/query operation may be deleted by entering "list" in place of the record number. BE CAREFUL with this, deleted records are really gone.
13. This choice starts a new menu with less commonly used functions. See MANAGEMENT MENU section below.
14. The program will prompt you for one-line Shell Commands until you enter just a <RETURN> to return to the main menu.
This is the screen to set up the region/mask/target information for the find choice (3) and the query choice (4), except that item B is omitted for choice (4). If a graphics monitor is not active, the "mouse" item is omitted from the menu; and, if a mask is not currently set, that line is omitted.
The choice to append or delete the selected records will only be given after a successful find or query has stored some records on the internal record list. When appending records, duplicates of those previously selected will be discorded--they will not be stored a second time. If neither append nor delete is selected, the find or query will begin a new internal record list and the previous contents will be lost.
The choices entered on this example screen will result in all the records within a 1500 (meters) radius of the target point (to be chosen with the mouse) being selected and stored on the internal record list by find or query. They are sorted and stored in order of proximity to the target. If a specific record is used as the target, it's representative point (label point) is the target coordinates, and it is always placed first in the retrieved list. If a mouse is chosen to select the target point, a menu to display reference maps is presented, exactly as in choice (6), prior to actually activating the mouse.
QUERY/FIND: REGION/MASK/TARGET SELECTION MENU
Data base <arch> (READONLY) in mapset <PERMANENT> open. 25 records.
Mark requests with 'x' and enter required values.
Respect current region x
Respect current MASK x
(forces current region)
A. Find all sites within (or outside) a circular target x
and give the radius (negative for outside) 1500.00_____
OR
B. Find a number of sites nearest a point _
and the number of sites requested ________
After selecting A or B, complete one(!) of these:
1. x to select target point with mouse x
2. Enter site number for target point __________
3. Target coordinates east 0.00________
north 0.00________
Append(a) or Delete(d) to the current FIND/QUERY list _
Reset to default choices for this menu _
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR <Ctrl-C> TO CANCEL)
QUERY COMMAND CONSTRUCTION SCREEN
Data base <wells> in mapset <grant> open. 25 records.
The SQL select query will use the current region
and a target clause of 'distance from 596463.15 4919041.88'
where date = 10/16/89 and ppm_Cr gt 10____________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
(Enter .show on a line to review screen layout and field names.)
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR <Ctrl-C> TO CANCEL)
v.db.rim DATA BASE MANAGEMENT MENU
Data base <fires> in mapset <Yellow> open. 250 records.
1 Make a New Data Base in Current Mapset
2 List Available Data Bases
3 Remove (PERMANENTLY) Data Base from Current Mapset
4 Recover a Data Base from a RIM ASCII File
5 Show Screen Layout of Current Data Base
6 Backup (UNLOAD) Data Base to RIM ASCII Format File
7 Pack the Current Data Base
8 Read a vector map into the Current Data Base
9 Execute a Bourne Shell Command Line
0 Return to Main Menu
0_ Your selection
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR <Ctrl-C> TO CANCEL)
1. Use this choice to create a new data base in the current GRASS
mapset. See section below on MAKE A NEW DATA BASE.
2. List available data bases. Like 2 on main menu.
3. Delete an entire data base from the current mapset. The name of the data base and additional confirmation of the action are prompted for. Be careful!
4. Choice 6 allows backup of the definition and data parts of a data base to a transportable text file. To rebuild (or build for the first time) a v.db.rim data base from one of these text files do the following steps:
# see if the rim directory exists.
ls $LOCATION/rim/vect
# if the directory was not found, make it.
mkdir $LOCATION/rim
mkdir $LOCATION/rim/vect
# change directory to it.
cd $LOCATION/rim/vect
# have rim build and load the binary data base files.
rim
RIM> input '/path/to/your/textfile'
RIM> exit
The data base is thus created in the current mapset. Several
v.db.rim commands should be run to verify the integrity
of the newly created data base.
5. This merely shows the screen layout of the currently open data base. It is a useful way to quickly see the layout and review the field names and types.
6. When backing up to a text file, the RIM UNLOAD command is run with the output directed to a file of the user's choice. See 4 above. It is wise to do this operation after extensive changes or additions of data records. The resulting text file can be written to tape for preservation, or shared with other GRASS systems, if desired. Data bases may also be backed up by copying the three binary files which comprise the data base to a different directory with the UNIX cp command.
7. After deleting and adding a large number of site records, some "wasted" disk space will be present in the binary data base files. This procedure will perform an unload and a reload automatically to recover this unusable disk space. If there is any problem reopening the data base after packing, the user is notified and can recover in various ways depending on the backups which have been done.
8. Data (records) may be loaded into a data base from an existing GRASS vector map. This procedure will prompt for the vector map name and then add a record to the currently open data base for each labeled(!) line in the vector field. The user may also enter the name of an integer field in which to store the label (from the dig_att file) for each vector, and a text field in which to store the descriptive text from the dig_cats file for each vector. The record number, vector type, map number and location coordinate fields (s,v,m,x and y types) are automatically loaded for each site record by this procedure; other fields may be later edited with the "change" function.
9. This choice is the same as choice 14 on the main menu.
The RIM Users manual by Jim Fox, Academic Computing Services, Univ. of
Washington. See especially Appendix B on redistribution of RIM.
The RIM Installers manual.
Last changed: $Date$