s.db.rim(1)		      Grass User's Manual		   s.db.rim(1)



NNAAMMEE
       ss..ddbb..rriimm  -  RIM  data  base management/query interface for GRASS sites
       data.
       _(_G_R_A_S_S _S_i_t_e_s _M_a_n_a_g_e_m_e_n_t _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ss..ddbb..rriimm
       ss..ddbb..rriimm _d_a_t_a___b_a_s_e

DDEESSCCRRIIPPTTIIOONN
	FFoorr ssoommee iinnffoorrmmaattiioonnss oonn LLIINNUUXX aanndd RRIIMM llooookk aatt tthhee BBUUGGSS sseeccttiioonn


       _s_._d_b_._r_i_m 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 (stan-
       dard input).  The _s_._d_b_._r_i_m 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_._d_b_._r_i_m.

SSEECCTTIIOONN OONNEE ---- TTHHEE CCOOMMMMAANNDD VVEERRSSIIOONN
       The command-line driven version of _s_._d_b_._r_i_m is run by typing the  below
       command,  where	_d_a_t_a___b_a_s_e  is  the  name of an existing RIM sites data
       base:


       ss..ddbb..rriimm _d_a_t_a___b_a_s_e



       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_._m_a_p_s_e_t_s 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.

CCOOMMMMAANNDDSS
       (Note:  For  each  of  the "dot commands", i.e., .make, described below
       there is a menu choice to selected when running	the  interactive  ver-
       sion.   The  interactive menus are described in the SECTION TWO of this
       document.  Some display capabilities exist in the  interactive  version
       which are not directly implemented in the command version.)


       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_._d_b_._r_i_m  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.


       AAllpphhaabbeettiiccaall CCoommmmaanndd SSuummmmaarryy



	      This  is	the  only _s_._d_b_._r_i_m command not starting with a period.
	      "command" is a single shell command line which is executed by  a
	      "G_system()"  call (see GRASS gis library).  Many UNIX utilities
	      (e.g., _v_i_, _l_s_, _p_r_i_n_t) and most  GRASS  commands  (e.g.,  _d_._r_a_s_t_,
	      _d_._p_o_i_n_t_s_, _g_._l_i_s_t_, _g_._r_e_g_i_o_n, _d_._z_o_o_m_, _r_._m_a_s_k) may be executed.  It
	      is permitted, and often useful, to change  "region"  and	"MASK"
	      within  _s_._d_b_._r_i_m_.   Multiple commands may be separated by ";" in
	      the standard UNIX way.  Note that a  "!cd  directory;  ls"  will
	      change to the specified directory and list files, but the effec-
	      tive working directory for _s_._d_b_._r_i_m will not be changed when the
	      command terminates.




       Add a new site record (row) to the open data base.  Each line following
       contains a field name followed by spaces and/or tabs then the value  or
       character  string to store for that field.  Field information lines end
       with .end.  Some fields may be absent and  fields  may  appear  in  any
       order.	Checks	are  made  for	the input of data for the one required
       field (site number), for string length for string type fields, and  for
       duplicate site numbers.	If split fields are used in the data base lay-
       out (see .make), text data for each split field must be added as a sep-
       arate  line.   If there are any problems, the record will not be stored
       and a message will be output.  This format makes it relatively easy  to
       import  data from most other DBMS.  The ".print -a" command, see below,
       outputs data in this list format.

       Example:

	.add
	site_id   204
	north	  4690673.30
	east	  601410.00
	reference Jones (1987)
	.end



       The .backup command is used to dump the entire data base from  the  RIM
       binary  files  to a text file format (see UNLOAD in the RIM User's Man-
       ual).  The file_name can be a relative path name  or  full  path  name.
       The  file will contain the data base definition, screen layout informa-
       tion, and tabular data.	This text file	is  transportable  to  RIM  or
       _s_._d_b_._r_i_m  running  on  any  other  computer; it may also be reloaded to
       recreate the _s_._d_b_._r_i_m data base.  A message will be output if there  is
       any  problem writing the .backup file.  Backup can only be done on data
       bases in the user's current mapset.


       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 some-
       where)
       GRASS 4.1> rm db_name.rimdb2	 #remove data base  (or  mv  to  some-
       where)
       GRASS  4.1>  rm	db_name.rimdb3	     #remove data base (or mv to some-
       where)
       GRASS 4.1> rim			 #run RIM manually
       RIM> input "path/file"		 #RIM rebuilds data base from data
					  written by .backup
       RIM> exit



       Without the "-l" flag, each line following .change is in the same  for-
       mat as for the .add command.  The site number field is required and the
       site number must match an existing site in the data base.   Only  those
       fields  for  which lines are provided are changed in the record.  After
       the .end the changed record is stored, if all is ok, otherwise  a  mes-
       sage is output.


       If  the "-l" flag (for "list") is given, the site number field is omit-
       ted and the specified field values are changed for all sites  currently
       selected by .find and/or .query.




       This  command  is  used	to delete data records for sites.  Deletion of
       sites is permanent.  A backup of the data base, or copies of  the  data
       base files, are the ways to protect your valuable data.


       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



       Ends multi-line input for several other commands.




       Use .exit to end operation of _s_._d_b_._r_i_m cleanly.	In general, do not use
       CTRL-C  to exit unless absolutely necessary.  When .exit is encountered
       in a batch file, input will revert back to the previous	file,  or  the
       terminal, if any, which called the batch file.




       The  .find command is used to find the site(s) closest to a given point
       (the target).  The target can be defined in one of several  ways.   The
       found  sites  are  stored on an internal sites list for output by other
       commands; however, see note 2, below.  The found sites  are  stored  on
       the internal sites list in order of proximity to the target location.


       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, select-
       ing 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 possi-
       bilities.

       find> 602793.90 4379010.00

       will find the one site nearest these coordinates and store  it  on  the
       internal site list.

       find> 619840 4599000 10

       will  find  the 10 sites (or fewer, if there are not that many) closest
       to the given location.

       find> site 132 10

       will 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 5000

       will find all sites within 5000 (meters, in  UTM  or  Lat-Long  coordi-
       nates) of the target location.

       find> distance from site 16 -2500

       will  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 cur-
       rent 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.




       Prints a help screen to the output device or file.  Useful to have when
       using  _s_._d_b_._r_i_m	from a terminal, or when writing a script file of com-
       mands.




       The lines in the file given are read and processed as commands or  data
       until  an  end  of  file  is reached or until a .exit command is found.
       Input files may call other input files to a  nesting  depth  of	eight.
       Without a file name, stdin is used as the input file.




       Lists the available data bases in the current mapset search path.




       Using  the  .make  command  you	create	a new data base in the current
       mapset by specifying the following items which define the screen (page)
       layout  for  displaying	and  printing the site records, as well as the
       information fields:


       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 pro-
       gram 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 spa-
       ces.


       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 val-
       ues  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  num-
       bers, use an "i" type field.)  In the example above, the northing coor-
       dinate (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.




       Causes all output (except some error messages) from _s_._d_b_._r_i_m, including
       that  from  the	.print command, to go to the named path/file (may be a
       full or relative path name), or to be used as  standard	input  by  the
       process	(a pipe).  If no parameter is given, output returns to stdout,
       usually the user's terminal.  An example of the pipe usage would be

	     .output | grep "easting" | wc -l > /tmp/my_count

       A pipe is closed whenever the .output command is given again, or  on  a
       .exit command.




       This  should  be  used  when numerous data records have been deleted to
       recover disk space in the RIM binary data  base	files.	 It  works  by
       doing  a .backup to a temporary file; moving the data base files to new
       names (*.bakdb*); running RIM to rebuild the data  base;  and,  if  the
       rebuilt	data  base  can  be  opened  and read, the temporary files are
       deleted.  The user is informed if this process fails.  Packing can only
       be done on an open data base located in the user's current mapset.




       This  command  outputs  the  full  site records for the sites currently
       stored on the internal sites list (result of  last  .query  or  .find).
       Without	the flag, the screen layout format is used.  With the -l flag,
       for list format, the field name followed by the contents are output one
       field per line.	The -a flag also outputs in the list format but with a
       .add line and a .end line surrounding each site	record	printed;  data
       files  in this form can be read with .input, thus they form one kind of
       backup mechanism and can be used to transfer data (not  the  data  base
       layout) from one GRASS system to another.  The destination for the out-
       put is set by a previous .output command (default is stdout).




       The .query command is used to retrieve sites via an SQL-like request to
       RIM,  including	a  user  specified "where clause." All fields for each
       site meeting the selection criteria are retrieved.


       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>.end

       The  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 com-
       mands.


       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 num-
       ber 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 unsuccess-
       ful ones), unless the -a or -d flags are used.




       This  command reads an existing GRASS site list and creates a data base
       record for each site. If  the  comment  or  description	field  of  all
       entries	in the site list begin with # and a number, the number becomes
       the site number in the data base.  If some of the sites	in  the  GRASS
       site  list  do  not have a # at the beginning of the comment field, the
       sites are numbered sequentially starting with 1.   (These  options  are
       similar to the way the GRASS sites-to-raster [in s.menu] works.)


       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.




       This  command,  which  requires a "y" as confirmation on the next line,
       entirely removes the three binary files which constitute your RIM  data
       base.  Use with care.  Backup files must be removed individually by the
       user, if desired, from the $LOCATION/rim/sites directory.




       This command is used to output the screen or page layout as defined for
       the  current  data  base.   It serves as documentation of the data base
       definition and as a reminder for field names, types  and  lengths.   By
       using  an  editor  to  surround the output of .show with .make and .end
       lines, it can be used to reload the data base definition with .input.




       This command writes the site locations and  the	site  numbers  to  the
       specified  file	in  the site_list directory in the current mapset.  If
       the file exists, the sites are appended to the current list, otherwise,
       a  new  site  list  file  is created.  A "field_name" may be optionally
       specified; if so, the contents of that field (retrieved from the appro-
       priate  site  record)  are inserted as the comment (following a '#') in
       the site list.  The site number is used if no field name is supplied.


       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



       Prints the table structure of the currently opened RIM data base.  This
       is  the	same  output  generated by a "list *" command when running RIM
       manually.  The information for the table named  "data"  is  useful  for
       review  of  the	user's field definitions.  The information for the two
       other tables is for internal use by _s_._d_b_._r_i_m_.




SSEECCTTIIOONN TTWWOO ---- TTHHEE IINNTTEERRAACCTTIIVVEE VVEERRSSIIOONN MMEENNUUSS AANNDD CCOOMMMMEENNTTSS
SSYYNNOOPPSSIISS
       ss..ddbb..rriimm

DDEESSCCRRIIPPTTIIOONN
       The interactive version of _s_._d_b_._r_i_m allows you to  create,  manage  and
       query  information  about  site locations (sites) across the landscape.
       Operations are done on a data base through a series of menus  explained
       below.	Most  of  the  menus  use VASK screens; the user should become
       familiar with keys that move the cursor among the fields to be  entered
       (RETURN, ENTER, CTRL-L, CTRL-K, etc.).

TTHHEE MMAAIINN MMEENNUU
       Below is the main menu.	Option 1 is the default.  Note the status line
       at the top of the menu, and the fact that 8 records have been  selected
       by  the	latest find or query operation (between items 2 and 3).  Note,
       also, that CTRL-C can be used to exit from this menu  (and  most  other
       menus  in the program) back to the GRASS prompt.  The specifics of each
       menu choice are described below.


	   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 cur-
       rent 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  loca-
       tion.   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 opera-
       tions, 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  com-
       parisons.   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 charac-
       ter.   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 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; dis-
       play  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 ver-
       sion 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  format-
       ting  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_._d_b_._r_i_m 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_._d_b_._r_i_m data base by writing site_lists with different
       fields as "comments" then converting the  site_lists  to  raster  files
       with _s_._m_e_n_u.


       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 num-
       ber.  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 val-
       ues 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,
       _d_e_l_e_t_e_d _r_e_c_o_r_d_s _a_r_e _r_e_a_l_l_y _g_o_n_e_.


       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  to return to the main menu.  Often  useful  for  changing
       the GRASS region, setting a MASK, etc.



FFIINNDD//QQUUEERRYY TTAARRGGEETT MMEENNUU
       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 informa-
       tion.


       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)



QQUUEERRYY CCOOMMMMAANNDD MMEENNUU
       The  following screen completes the information for a query (choice 4).
       It may be left blank if no "where clause" is required.	After  a  suc-
       cessful query, the selected records are displayed one at a time by hit-
       ing escape; CTRL-C will quit the display and return to  the  main  menu
       where  several choices of operation on the retrieved sites are offered.


	       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)



MMAANNAAGGEEMMEENNTT MMEENNUU
       Choice 13 from the main menu presents this menu.   Each	item  is  dis-
       cussed below.


	 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_._d_b_._r_i_m 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_._d_b_._r_i_m data base from one of these text files do the  follow-
       ing 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_._d_b_._r_i_m
       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 unus-
       able 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  sequen-
       tially 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.



MMAAKKEE AA NNEEWW DDAATTAA BBAASSEE
       After  entering	the  name  of  the new data base you wish to create (7
       characters maximum), you then  decide  how  to  input  the  information
       required.   This  input	may  be  from  a  text file, or may be entered
       directly using the editor of your choice; the former is recommended.


       See .make for the way to define a data base and record (form) layout.



NNOOTTEESS
       This program is included in the GRASS 4.0 release, but is not automati-
       cally  compiled	with other GRASS commands.  The user must compile this
       program separately.


       _s_._d_b_._r_i_m interfaces to the RIM program.	Both _r_i_m and _s_._d_b_._r_i_m  contain
       FORTRAN code.  The user must have access to a FORTRAN compiler in order
       to compile and use _s_._d_b_._r_i_m.  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.



BBUUGGSS
       On  LINUX  I have some problems: - If You select menu 13/8 and hit ESC,
       there is no output to the screen. _s_._d_b_._r_i_m expects here the name of the
       site  file  or  the keyword _l_i_s_t.  - If You select menu 8, You hould be
       asked for the site_list filename, but the screen remains empty.	Simply
       enter the name.


FFIILLEESS
       The source code for RIM is located under $GISBASE/../src.related/rim


       The  source  code  for  _s_._d_b_._r_i_m  is located under $GISBASE/../src.gar-
       den/grass.rim/s.db.rim

SSEEEE AALLSSOO
       The RIM User's Manual by Jim Fox, Academic Computing Services, Univ. of
       Washington.  See especially Appendix B on redistribution of RIM.

       The RIM Installers manual.


       _G_R_A_S_S  _4_._1  _I_n_s_t_a_l_l_a_t_i_o_n  _G_u_i_d_e, 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

AAUUTTHHOORRSS
       James Hinthorne and David Satnik, GIS  Laboratory,  Central  Washington
       University, Ellensburg, WA.



       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_5 _$



GRASS 5.0							   s.db.rim(1)
