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
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
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.
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
Selected low-level routines
All routines below operate on 2D integer matrices where entries are stored in columns, i.e., x(:,i) is one entry
1. Hash insertion and retrieval
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