s.db.rim allows users to create, manage and query information about site locations (sites) across the landscape. Required inputs can be entered interactively, or from the command line. Command line input may be entered through a prepared text file or from the keyboard (standard input). The s.db.rim command language is defined in SECTION ONE below. The menu-driven interactive version is described in SECTION TWO of these manual pages.
These programs are 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 as FORTRAN 77 code. Your system must have a FORTRAN 77 compiler to use s.db.rim.
The sites data bases are stored in a subdirectory named 'rim/sites' in the user's current mapset. Data bases in other mapsets, selectable through the GRASS g.mapsets command, can be accessed for 'read-only' retrieval of records. Each mapset may have many data bases. Each data base within a mapset must have a different name; user-supplied names for data bases are limited to seven (7) characters in order to maintain compatibility with the standard version of RIM. As with other GRASS commands, mapsets are searched in the mapset SEARCH_PATH order when a data base needs to be opened.
Each site data base is composed of multi-field records (rows or tuples, in DBMS jargon). Each field and its position in the site 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 and is not described here; 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 sites.
The commands are given alphabetically here for easy reference. The .make command is required to create a data base and, therefore, will be the first to be entered by a new user. Abbreviations down to the string shown in ( ) are accepted; this is primarily for those giving s.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 are supplied on successive lines; a .end line is needed by some commands to signify the end of these input lines.
Alphabetical Command Summary
Example: .add site_id 204 north 4690673.30 east 601410.00 reference Jones (1987) .end
To reload your data base from the backup file (normally not necessary):
GRASS 4.1> cd $LOCATION/rim/sites #right directory
GRASS 4.1> rm db_name.rimdb1 #remove data base (or mv to somewhere)
GRASS 4.1> rm db_name.rimdb2 #remove data base (or mv to somewhere)
GRASS 4.1> rm db_name.rimdb3 #remove data base (or mv to somewhere)
GRASS 4.1> 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 site number field is omitted and the specified field values are changed for all sites currently selected by .find and/or .query.
The lines following the .delete command should contain only the site numbers, with a .end line being last.
The following command sequence will delete all the sites currently on the internal site list (the result of the last .query or .find command) after asking for approval.
.delete .end
The optional .find command line parameter specifies the current MASK (-m), if any, or the current region (-r), as a filter on the retrieved sites. -m automatically implies -r, as the MASK is not defined outside the current region. If the -a flag is given, the retrieved sites will be appended to those previously retrieved with a .query or .find; duplicates will be automatically discarded. The -d flag causes the retrieved sites to be deleted from the internal site list, if present there. Very complex selections can be done by interspersing appends and deletes to arrive at a final list of sites. For instance, selecting those sites within 2000 meters of a target and then deleting those within 1500 meteres of the target will give a final list of those from 1500 to 2000 meters.
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 site nearest these coordinates and store it on the internal site list.
find> 619840 4599000 10will find the 10 sites (or fewer, if there are not that many) closest to the given location.
find> site 132 10will find the 10 sites closest to the location of site 132 in the data base (including site 132). If site 132 does not exist, no action is taken.
find> distance from 472910.06 5732001.0 5000will find all sites within 5000 (meters, in UTM or Lat-Long coordinates) of the target location.
find> distance from site 16 -2500will find all sites greater than 2500 (meters) from the location of site 16.
Notes for .find:
1. All sites found are stored on the site list in order of proximity to the target location (sorted by distance from target).
2. The number of sites 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 in the masking map.
5. In the last two examples the string "distance from" must be exactly matched. Also, the word "site" 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.
1) The fixed text part of the screen layout.
2) The positions, types, names and lengths of data fields.
Three 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' Site identification number field (an integer).
2) Type 'x' Easting coordinate of the site (a double float).
3) Type 'y' Northing coordinate of the site (a double float).
The other field types, which may occur in any combination and order, are:
4) type 'i' An integer field.
5) type 'f' A double precision float field.
6) 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 important explanatory notes.
.make
Archaeological Sites Database
=============================
Site #: ~sSite~~~ Entered By: ~tEnter_by~~~~~~~~
Description: C-14 Date: ~iAge~~~
~tDescript.1~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~tDescript.2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~tDescript.3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Type: ~tType~~~~~~~~~~~~~ (Should be Arch. or Hist.)
Date: ~tEnter_Date~~~~~~~ Square Miles: ~fArea.4~~~
North: ~yNorth~~~~~ East: ~xEast.1~~~~
.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,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 required maximum length.
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.
5) For the double precision floating point fields (types x, y and f), the number of decimal places to print may be specified by appending ".n" to the field name, where n is the number of decimals places required. Values of n from 1 to 12 may be used. Two decimal places is the default if ".n" is not specified. Be certain that you make the field wide enough to print the integer and decimal portions of the values that will be stored in the field; include space for a sign and the decimal point. (If it is desired to print zero decimals, whole numbers, use an "i" type field.) In the example above, the northing coordinate (y) would be output with two decimals, the easting (x) would have only one decimal place, and the "Area" would be printed with four decimal places.
.output | grep "easting" | wc -l > /tmp/my_count
A pipe is closed whenever the .output command is given again, or
on a .exit command.
The optional .query command line parameters cause points not in the region (-r) and/or mask (-m) to be rejected, so these conditions need not be tested in the "where clause." The -a flag causes the retrieved sites to be appended to those previously retrieved by .query or .find; duplicate entries are automatically discarded. The -d flag causes selected sites to be deleted from the current list, if present.
After the query command line, any number of lines 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 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> .end Example 2 query> where east <600000 and name like "*Jones*" query> distance from site 12 3000 query> .print -a query> .end Example 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 sites will be retrieved (Example 3). When querying for sites the where clause is processed first, the current region and mask tested next (if requested), then the distance from clause is applied; a site must pass all tests to be put on the internal site list for output by other commands.
Notes: (Also see Notes for .find)
1. The retrieved sites are stored on the internal site list in the order returned from the data base by RIM, not necessarily in site number order or the order the data was loaded. A "distance from" clause results in a final sorting by proximity to target.
2. See the RIM User's Manual for additional information on the "where" clause in the "select" command, especially the quotes required for matching character string fields, and the allowed comparison operators.
3. In the where clauses of the examples, "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 site list (even unsuccessful ones), unless the -a or -d flags are used.
if a data base field name "comment_field" is entered on the command line, the comment will be stored in that field for each site. If an integer or float field is specified, and attempt is made to interpret the comment as that type of number; if this interpretation fails, 0 or 0.0 is stored.
If the site number duplicates one already in the data base or found earlier in the site list, it is not added.
Once the sites have been loaded by .read_site, use .change (or the interactive version) to add data to other fields for those sites.
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|#comment
s.db.rim MAIN MENU Version 1.4
Data base <water> in mapset <rono> open. 25 records.
1 Open a data base
2 List available data bases
-------- Retrieve/Output Site Records (8 currently) --
3 Find sites in proximity to a Target point
4 Query to select site records (SQL)
5 Show selected site records on Terminal
6 Display maps/selected sites on graphics terminal
7 Output selected site records to Printer or File
8 Create a site_list from selected records
------------ Add/Edit Site Records ----------
9 View a single site record
10 Add a site record
11 Change a site 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 s.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.
2. List available data bases. For each mapset in the current GRASS mapset search path, the names of the existing data bases are listed.
3. "Find" sites in the data base relative to a specified target location. This is used to select sites based on proximity to the target and, optionally, sites within the current region and, optionally, sites falling in active cells within the current GRASS mask. Two modes of targeting are provided: the N sites closest to the target, and all sites 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 sites are then displayed one at a time until CTRL-C is entered; then other operations, choices 5-8, can be done with these sites. The line on the menu between 2 and 3 shows the number of sites currently selected by choices 3 or 4.
4. "Query" sites 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 sites are then displayed one at a time until CTRL-C is entered; then other operations, choices 5-8, can be done with these sites. This clause is entered on a menu described below; see QUERY COMMAND MENU section, 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 notThe 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 site 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 locations of the selected sites will be displayed. The user may choose to erase the screen; display raster, vector, and/or site maps; or display the selected sites from the data base. These maps are requested through the following interactive screen. Just enter ESC to skip this step. If no data base sites 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. This display function is a major added function of the interactive version of the program; display is not so easy in the command version.
SELECTION MENU FOR ITEMS TO DISPLAY
Enter raster and/or vector map names, if desired
______________ Raster map to display
______________ Vector map to display in color: _________
______________ Site list to display
Dpoints with: size=3_ type=box____ color=white____
_ Display currently selected sites (enter x)
d.sites with: size=6_ type=x______ color=red______
_ Erase graphics screen (enter x)
d.erase 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 site 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
format (see .print in the first part of this manual page for
s.db.rim
for information and examples).
8. Using this choice you can write (or append) the currently selected sites to a GRASS site_list file in your current mapset. A short menu prompts for the name of the site_list file, and also for the name of a field to be used for the "comment" in the site_list (the site 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 various kinds of raster map layers can be produced from a s.db.rim data base by writing site_lists with different fields as "comments" then converting the site_lists to raster files with s.menu.
9. Choices 9-12 operate on only a single site and do not use or modify the internal list of sites selected by find/query (choices 3 or 4). Choice 9 is the way to view a single site record, selected by site 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 site record to the data base. (A new site is one whose site 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 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 site number to change field information for, the data is entered as for choice 10, except that the site 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 site number when requested. All site records chosen by the last find/query operation may be deleted by entering "list" in place of the site 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. Often useful for changing the GRASS region, setting a MASK, etc.
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). The choice to append or delete selected records will only be given after a successful find or query has stored some records on the internal record list. See .find and .query for more information.
If a graphics monitor is not active, the "mouse" item is omitted from the screen; and, if a mask is not set, that choice is omitted. The choices entered on this example screen will result in all the sites within a 1500 (meters) radius of the target point (to be chosen with the mouse) being selected and stored on the internal site list by find or query. They are stored in order of proximity to the target. If a site is used as the target, it is always the first in the retrieved list (useful for just selecting one site by number). 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. 113 records.
Mark requests with 'x' and enter required values.
Respect current region _
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/Delete to current FIND/QUERY site list (a | d) _
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 <A> in mapset <rim_test> 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_____________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
__________________________________________________________
(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)
s.db.rim DATA BASE MANAGEMENT MENU
Data base <A> in mapset <rim_test> open. 15025 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 Site list into the Current Data Base
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 s.db.rim 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.
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 s.db.rim data base from one of these text files do the following steps:
# see if the rim directory exists.
ls $LOCATION/rim/sites
# if the directory was not found, make it.
mkdir $LOCATION/rim/sites
# change directory to it.
cd $LOCATION/rim/sites
# have rim build 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
s.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.
7. After deleting 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 may be loaded into a data base from an existing GRASS site_list. This procedure will prompt for the site_list name and then add the sites to the currently open data base. If all sites in the list have a comment field of the form "#value ....", the value is used as the data base site number, otherwise the sites are numbered sequentially beginning with 1. Only the site number and location coordinates are loaded for each site record by this procedure; other fields may be later added with the "change" function. See .read_sites.
See .make for the way to define a data base and record (form) layout.
s.db.rim interfaces to the RIM program. Both rim and s.db.rim contain FORTRAN code. The user must have access to a FORTRAN compiler in order to compile and use s.db.rim. See the FILES section, below, for the location of source code.
A "date" type field should be added to future versions. This version only allows storing of dates as strings (unless the user codes them to integers), and thus only string type searches can be made for dates.
The source code for s.db.rim is located under $GISBASE/../src.garden/grass.rim/s.db.rim
GRASS 4.1 Installation Guide, by Jim Westervelt and Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
d.icons
d.points
g.mapsets
g.region
r.mask
s.in.ascii
s.menu
s.out.ascii
v.db.rim
Last changed: $Date: 2002/01/25 05:45:35 $