isf.f90 - an indexed and sequential file organization Original release: May 16, 1995. Version 1.02 revised release: Jan 1, 1997. Version 1.10 (elf90 and F version) Note: This is the documention for version 1.10 of isf. 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 sequentially 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 type 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 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 all subroutines in this package. Subroutine : IS_FILE_OPEN(is_block, fname, unit1, unit2, err) was a function in ver 1.02: 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) This is set to .not. associated on an error. 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 occurred, 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 occurred, 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, 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 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, 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 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, 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 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 occurred, 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 occurred, 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, 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 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, 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 has not been found. --------------------------------------- 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.