pkf - positional key file documentation and rational

This package contains one Fortran 90 module, with several subroutines.
The fundament 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 direct access, when a record
is written, the write routine returns a key.  This key is used as parameter
to the "get" routine to retrieve a record; therefore the program should
keep track of the keys returned, because it is necessary to use them to
read back the records.

Perceived flaws in Fortran standard access=direct.
 - No way to know how many records are on a file.
 - No way to know if a specific record has ever been written.
 - No way to delete a record.

One of the objectives of this file type is to create the basic functionality
of the "Actual Key" file organization used by Control Data's Cyber Record
Manager.  However, the routines supplied here are not exactly compatable with
those used in CRM.

When a record is deleted, the space used by that record is available
for later reuse.  Any attempt to read a deleted record will return
an error status.

The key of the first record written to a file will be 1, for subsequent
writes, a simple integer sequence of key numbers will be used, (2, 3, 4...)

Limitation: This file organization must use a fixed length record. (A
specific derived data type).

Subroutines and parameters:

Subroutine  : PK_FILE_CREATE( name, unit, err)
              Create a new PK file.
       name : file name, required (character string)
       unit : unit number, optional(integer) Fortran logical unit to use,
              if this is not supplied, the routine will choose a currently
              unused unit number.
        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    : PK_FILE_OPEN( name, unit, action, err) result(pk_rno)
              Open an existing PK file.
   pk_block : function return, pointer to 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)
       name : file name, required (character string)
       unit : unit number, optional(integer) Fortran logical unit to use,
              if this is not supplied, the routine will choose a currently
              unused unit number.
     action : read-write or read only, optional(character string)
              must be 'read' or 'readwrite',  the default is 'readwrite'.
        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.

Subroutine  : PK_FILE_CLOSE( pk_block, err)
              Close an currently open PK file.
   pk_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.

Subroutine  : PK_GET_RECORD( pk_block, pk_rno, data_record, err)
              Read a record from an open file.
   pk_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
     pk_rno : record number to retrieve, required(integer)
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 been deleted.
              -2 implies that the record number pk_rno, is out of
              the range of possible records on the file.

Function    : PK_NEW_RECORD( pk_block, data_record, err) result(pk_rno)
              Writes a new record on the file.
     pk_rno : function return, new record number assigned to this
              new record(integer)
              -1 implies this record could not be written, see err below.
   pk_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.

Subroutine  : PK_PUT_RECORD( pk_block, pk_rno, data_record, err)
              Rewrites the data in an existing record.
   pk_block : control information, required(derived data type)
              This is dynamically allocated in the open routine.
     pk_rno : record number to rewrite, required(integer)
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 has been deleted.
              -2 implies that the record number pk_rno, is out of
              the range of possible records on the file.

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