Module HASH_DB

Written by Ignacy Misztal, University of Georgia June 6, 2001 - July 16, 2001

Module hash_db implements simple database(s) using hash tables in memory and Fortran 90. Operations include:

1. declare a table

  	type (db_hash)::x

 where x is a database
 

2, Initialize

call init(x)

3. Declare fields

call add_field(x,name,type,n)

 where alphanumeric variable name contains name of field, type is 
 alphanumeric	field specifying type of variable as "character", "integer",
 or "real", and n is optional variable that specifies length of 
 "character" field.
 

4. Indicate which field is an index

 	call set_index(x,name)

 where name is an alphanumeric variable containing the name of field that 
 will serve as index. All searches are by the index.

5. Indicate that all field definitions are provided

call align_db(x)

6. Specify the initial number of elements in the table:

call zero(x,n)

 where n contains the maximum number of elements
 warning: this subroutine calls subroutine "align" if needed.
 		
 

7. Insert elements

call insert_el(x,name,val)        

 where name is name of field and val its value; the type of val corresponds
 to the type of field. Insertion is into the current record. However, if 
 the field is an index, the action depends on whether a record with
 val as an index exists. If it does, that record will become the current
 record. If not, such a record will be created and it will become the current
 record.

8. Reposition pointer to a current record

stat=move_rec(x,direction)

 changes the current record according to value of variable direction: 
 "next","previous", "first","last". Logical variable stat is .true. if the 
 operation is successful and .false. otherwise.
 

9. Retrieve elements

      stat=find_index(x,val)
   
   tries to locate an entry with index value val; if successful, stat is
   set to .true. and that entry becomes the current entry; if not successful,
   stat is set to .false.	

call get_el(x,name,val) 

   retrieves value of field name from the current record into variable val.	   

Additional subroutines/functions

A. Printing

call print_entry(x,form,un)

prints the current entry; 
optional form specifies format
optional un specifies unit; by default the output goes to the terminal
	

call print_table(x,form,un)

prints all entries
optional form specifies format
optional un specifies unit; by default the output goes to the 
terminal
	

B. Printing database information

call print_setup(x)

 shows order of fields and their physical location in table x

C. Reading and writing

      call write(setup(x,name)

 writes setup of the database (but not entries) to file name
 
      call write_data(x,name,form)

 writes contents of the database to file name; optional form has values
 "character" for character storage (default) or "binary" for binary storage.
 
      call read_setup(x,name)

 reads setup into an existing or empty database from file name.
 
      call read_data(x,name,form,nel)

 reads contents of database from file name into x; optional form is
 "character" or "binary"; optional nel specifies the maximum number of
 elements in the table. If nel is absent, that number is 1.25 times the number
 of entries.	
 
      call expand(x,n)

 increases the maximum number of entries twice, or to n if optional
 n is present.
 

D. Sorting, clustring, numbering, etc.

     call add_count(x,field,type)
     
adds consecutive numbering from 1 to given field;
if optional type='sorted', then entries are numbered by increasing
indixes; otherwise, numbering is by random order.

  	subroutine sort_db(x,fields,order)

sorts x specified by optional field and order
if optional fields are missing, sort by index in asecnding order

fields is a character variable containing fields to be sorted; fields
are separated by spaces
optional order is 'a' for ascending and 'd' for descending order


 

 	i=hashv1(x,ind,mode,nr)

 tries to find such i: x(1:size(ind),i) = ind
 if unsuccessful, then:
 
     if mode=0 (writing):
        ind is stored in an empty (all 0) location and i is set to that
  location; if there is no space, i is set to -1
  
     if mode=1 (retrieval):
        i is set to 0 
    

      call sort(x,col,n)

  sorts columns x by rows in vector x; if optional n is present, only 	
  first n columns are sorted.
  

  
      call clustermat(x,n)

  clusters columns of x with nonxero first-row at the beginning of the matrix;
  n is set to the number of nonzero elements
 
      call