pkf - positional key file documentation (ver 1.10) Copyright (c) 1997, 2008 Garnatz and Grovender, Inc. Original release: May 16, 1995. Version 1.02 revised release: July 28, 1995. Version 1.03 (f77 version and more error checks) revised release: Jan 1, 1997. Version 1.10 (elf90 and F version) 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 type 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 identical 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 occurred, 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 almost all other subroutines in this package. Subroutine : PK_FILE_OPEN( pk_block, name, unit, action) Open an existing PK file. (Note: this was a function is versions 1.0x) pk_block : returned 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) On errors, this pointer will returned null (.not. associated()) 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'. 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 occurred, 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, required(derived data type) err : error flag, optional(integer) A non-zero return indicates a problem has occurred, 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. Subroutine : PK_NEW_RECORD( pk_block, data_record, pk_rno) (Note: this was a function is versions 1.0x) 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, required(derived data type) Subroutine : PK_NEW_REC_NUM( pk_block, pk_rno) (was a function in version 1.03) allocate a new record number on the file. pk_rno : function return, new record number assigned to a new record (integer) -1 implies that a new record location could not be allocated pk_block : control information, required(derived data type) This is dynamically allocated in the open routine. 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, required(derived data type) err : error flag, optional(integer) A non-zero return indicates a problem has occurred, 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. Subroutine : PK_DELETE_RECORD (pk_block_KEY, pk_rno, err) pk_block : control information, required(derived data type) This is dynamically allocated in the open routine. pk_rno : record number to delete, required(integer) err : error flag, optional(integer) A non-zero return indicates a problem has occurred, zero implies correct result. --------------------------------------- Notes on Fortran 77 version --------------------------------------- The Fortran 77 version requires more customization than the Fortran 90 version. A parameter(sizeof_int=4) must be modified to the number of storage units of an integer on your specific hardware, this is needed for the access=direct I/O size= option on an open. Other sizing constant will also need to be modified. Your data, called data_item_1, 2, 3, 4 can be any data type you wish, the original code is set up for type character. If you change to a different type, one temporary variable must be defined in an appropriate common block. Two data items are included in the prototype, if you want more or less, the source must be modified; commented out values are included for up to 4 data items. A set of COMMON blocks hold the control information, so the "pk_block" first argument to the subroutine calls is omitted. For example the Fortran 90 routine: PK_PUT_RECORD( pk_block, pk_rno, data_record, err) looks like this is Fortran 77: PK_PUT_RECORD( pk_rno, data_record, err) --------------------------------------- Software License Agreement Application: --------------------------------------- TO: | FROM: Garnatz and Grovender, Inc. | __________________________________ 17 South 1st St. A1202 | Minneapolis MN 55401-1831 |Company: _________________________________ email: gginc@gginc.biz | |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 ______ * "HKF" Diskette with programs and documentation ........... $50 ______ * "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 "HKF" and "PKF" routines. (INCLUDES ONE DISKETTE WITH PROGRAMS AND DOCUMENTATION.) level 1: only 1 developer, and up to 10 runtime copies $130.00 ______ level 2: up to 10 developers, and up to 100 runtime copies $370.00 ______ level 3: unlimited developers, and unlimited runtime copies $2600.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 ______ Minnesota 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 three products currently available for license. "PKF" is the "Positional Key File Module" written in Fortran 90 or Fortran 77. "HKF" is the "Hashed Key File Module" written in Fortran 90 or Fortran 77. - A license to use "HKF" at any of the four levels available includes an implicit license to use "PKF" at the same level. "ISF" is the "Indexed Sequential 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", "HKF" and "ISF" file management routines are Shareware, and 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 methodology to create a multiple key version of the "ISF" program is available. A explanation of how to do this, complete with sample programs is available to registered "ISF" users.