is.f90 - an indexed and sequential file organization

A totally missing file type in Fortran. It is often useful to be able
to access data by a key, and then read sequentially.

- read, write and delete a record by key
- skip to the beginning or end
- read sequentialy forward and backwards
- ability to delete a record.

This package contains one Fortran 90 module, with several subroutines.
The fundamental unit of input and output is a derived data type. (This
is usually referred to as a "structure" or "record" in other popular
computer languages).  The source code will be modified by the programmer
to reflect the data tyoe to be read and written.

This file organization is different than either sequential or direct access,
when a record is written, it is written by key, this key is used as one of the
ways to retrieve a record; this key can also be used to access the records
and to read back the records.

One of the objectives of this file type is to create the basic functionality
of the "Indexed Sequential" file organization; used by many computer makers
Operation Systems.  Also known and VSAM, ISAM and other names, like b-tree or
b-plus-tree.

Limitations: This file organization must use a fixed length record. (A
specific derived data type); and only one key is supported at this time.

Subroutine and parameters:

Subroutine  : IS_FILE_CREATE(fname, unit1, unit2, err)
              Create a new IS file.
      fname : file name, required (character string), internally an unused
              unit number will be chosen and used
      unit1 : Fortran unit number, optional(integer), used to create the
              index file, if not supplied, an unused unit number will be
              chosen internally.
      unit2 : Fortran unit number, optional(integer), used to create the
              data file, if not supplied, an unused unit number will be
              chosen internally.
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              If a unit number is not supplied, the error code of -99
              means no unit number is available. All other
              returns are error status from open, read or write and
              are system dependent. This parameter is available on all
              subroutines in this package.

Function    : IS_FILE_OPEN( fname, unit1, unit2, err) result(is_block)
              Open an existing IS file.
   is_block : function return, derived data type of control information.
              This is dynamically allocated in this open routine, and is
              a required parameter for all other calls. (except for create)
      unit1 : Fortran unit number, optional(integer), used to create the
              index file, if not supplied, an unused unit number will be
              chosen internally.
      unit2 : Fortran unit number, optional(integer), used to create the
              data file, if not supplied, an unused unit number will be
              chosen internally.
      fname : file name, required (character string)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              If a unit number is not supplied, the error code of -99
              means no unit number is available.

Subroutine  : IS_FILE_CLOSE( is_block, err) Close an currently open IS file.
              is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine, and
              deallocated here.
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.

Subroutine  : IS_GET_RECORD( is_block, is_key, data_record, err)
              Read a record from an open file.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
     is_key : key of record to retrieve, required
data_record : where to put the retrieved data, requied (derived data type)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record has has not been found.
              other errors are system dependent.

Subroutine  : IS_PUT_RECORD( is_block, data_record, err)
              Writes a new data record.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
data_record : data to write on the file, requied(derived data type)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record already exists.

Subroutine  : IS_REPLACE_RECORD( is_block, data_record, err)
              Writes the data in an existing record.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
data_record : data to write on the file, requied(derived data type)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record does not exist.

Subroutine  : IS_DELETE_RECORD(is_block, is_key, err)
              Deletes a record from an open file.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
     is_key : key of record to delete, required
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record has has not been found.
              other errors are system dependent.

Subroutine  : IS_POS_BEGIN(is_block, err)
              Rewinds the file, positions so then the next sequential
              read will read the first record on the file.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.

Subroutine  : IS_POS_EOF(is_block, err)
              Positions so then the next sequential backwards
              read will read the last record on the file.
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record has has not been found.

Subroutine  : IS_GET_NEXT_RECORD(is_block, data_record, err)
              Reads the next sequential record
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
data_record : where to put the retrieved data, requied (derived data type)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record has has not been found.

Subroutine  : IS_GET_PREV_RECORD(is_block, data_record, err)
              Reads the next sequential record
   is_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
data_record : where to put the retrieved data, requied (derived data type)
        err : error flag, optional(integer) A non-zero return indicates
              a problem has occured, zero implies correct result.
              -1 implies this record has has not been found.

---------------------------------------
Software License Agreement Application:
---------------------------------------
TO:                         | FROM:
Garnatz and Grovender, Inc. |        __________________________________
5301 26th Avenue South      |
Minneapolis MN 55417-1923   |Company: _________________________________
email: gginc@winternet.com  |
612-722-3094 Voice          |Address: _________________________________
                            |
                            |City:   __________________________________
Today's                     |
date: ___________           |State, ZIP Code: _________________________
                            |
                            |Country: __________________________________
Daytime
Phone #: _________________________  FAX #: ____________________________

Diskette size (MS-DOS):  5 1/4" _____   3 1/2" ______


INDIVIDUAL USE:  1 developer with source, only 1 runtime copy
   level 0:
  * "PKF" Diskette with programs and documentation ........... $45   ______
  * "ISF" Diskette with programs and documentation ........... $95   ______
         (ISF includes PKF)

MULTIPLE USE:
 * SITE LICENSE for the use of "ISF" and "PKF" routines.
    (INCLUDES ONE DISKETTE WITH PROGRAMS AND DOCUMENTATION.)
   level 1:
   only  1 developer, and up to 10 runtime copies       $250.00      ______
   level 2:
   up to 10 developers, and up to 100 runtime copies    $850.00      ______
   level 3:
   unlimited developers, and unlimited runtime copies  $7500.00      ______

 * SITE LICENSE for the use of "PKF" routines.
    (INCLUDES ONE DISKETTE WITH PROGRAMS AND DOCUMENTATION.)
   level 1:
   only  1 developer, and up to 10 runtime copies       $120.00      ______
   level 2:
   up to 10 developers, and up to 100 runtime copies    $350.00      ______
   level 3:
   unlimited developers, and unlimited runtime copies  $2500.00      ______


Shipping & Handling (Postal) US & Canada $5.00
Outside US & Canada $11.25                                           ______

Minnnesota RESIDENTS add applicable State Sales Tax (6.5%)           ______
  (Minneapolis RESIDENTS  7% instead of 6.5%)
TOTAL ENCLOSED US FUNDS                                         US$ _______

TERMS:
  Check or Money Order in U.S.A. funds.
  Corporate Purchase orders (Net 30 days) accepted for
  software from large corporations within the USA & Canada.
  ALL LICENSES ARE PREPAID ONLY.  ALL ORDERS OUTSIDE OF THE UNITED STATES
  AND CANADA MUST BE PREPAID.  Please make remittance payable to Garnatz
  and Grovender, Inc.   Prices and terms subject to change without notice.

INFORMATION ON LICENSING

There are two products currently available for license.
"PKF" is the "Positional Key File Module" written in Fortran 90.
"ISF" is the "Indexed Sequentail File Module" written in Fortran 90.
A license to use "ISF" at any of the four levels available includes an
implicit license to use "PKF" at the same level; this is because the
indexed sequential file handler makes use of two copies of "PKF",  One
for the data, and one for the index.

USE ON MORE THAN ONE COMPUTER

To use Garnatz and Grovender, Inc. products in a commercial, educational
or governmental agency on more than one computer, it is necessary to
purchase a MULTIPLE USE or SITE LICENSE.  The Site License allows the
organization to use the source code for development of software packages
on up to the number of computers licensed.

Site License fees are based on the total number of programmers that
will use the software "source" code for development and separately for
the number of copies of the program that will be used on the same or
other computers at runtime or sold as part of a software package.
Please use the "MULTIPLE USE" portion of the order form in this file.

NOTE THAT THE SITE LICENSE INCLUDES ONE COPY OF THE SOFTWARE AND DOCUMENTATION.

The Site License allows you to copy it for the number of machines licensed for
the specified use, source code for development or runtime.
Distributing, repackaging, or reselling of the software to that includes the
routines is included in the number of runtime copies.


BENEFITS OF OBTAINING A LICENSE
-------------------------------------------------------------

The "PKF" and "ISF" file management routines are Shareware, and if you
are requested to obtain a proper license and register your organization
as a legal user.

With registration you will receive the latest version of the software,
a comprehensive printed manual, free upgrades of the software for at
least one year.

Also included in the registered version are utility programs not provided
in the shareware public distribution version.

A effort to create a multiple key version of the "ISF" program has been
started, the time of completion of this project will be directly affected by
the level of financial support for the single key version.
