home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / c / kafsrt20.zip / KAFS.DOC < prev    next >
Text File  |  1993-05-29  |  9KB  |  332 lines
  1. KAFS - Keyed Access File System
  2.  
  3. KAFS (INCLUDING SORT) IS SHAREWARE AND MUST BE REGISTERED AFTER
  4.                      A 30 DAY TRIAL PERIOD.
  5.  
  6.  
  7. Overview
  8. KAFS is a full featured file system that provides extremely fast
  9. access times as well as a simplified interface. KAFS is a unique
  10. file system that does not follow the traditional roles of ISAM
  11. (Indexed Sequential Access Method), BTREE (Binary Tree), or
  12. other such file systems. KAFS was designed to provide maximum
  13. speed while retaining the simplicity needed to quickly design
  14. and build applications that would use its facilities. KAFS is a
  15. 'programmer's file system'. It provides ample functions to get
  16. the job done and provides one of the fastest file access times
  17. of any file system available today.
  18.  
  19.  
  20. What is Keyed Access?
  21. A keyed access file system is one which performs record
  22. searching and retrieval based on a 'key' field pertaining to the
  23. data. Many other types of file system, such as those mentioned
  24. above, use this methodology as well. The differences between
  25. these systems lies in the actual processes used to search for
  26. keys and in the data retrieval processes. Each method has is own
  27. distinct advantages which this document will not attempt to
  28. delve into. We will describe how KAFS functions and explain the
  29. processes it uses to search keys and extract data from the file
  30. system.
  31.  
  32. Simply stated, keyed access is access to records in a file based
  33. on a key field associated with the record.
  34.  
  35.  
  36. Sizing Records and Files
  37. Record and file sizing must be done by the KAUTIL program for
  38. all KAFS files. Records sizes defined by the KAUTIL program (in
  39. File Create / Initialize) must EXACTLY math the record size in
  40. the 'C' programs that will access it. Use the 'sizeof' function
  41. to determine the size of your record structure in your 'C'
  42. program and pass this on to the KAUTIL program when creating the
  43. file. 
  44.  
  45.  
  46. File sizing is always an estimated guess of some sort. The goal
  47. is to create a file size that will never exceed 80% of total
  48. capacity and will yield a good hash distribution (See record
  49. hashing explained).
  50.  
  51. See Production System Documentation .....
  52.  
  53.  
  54. The KATEST program
  55. The KATEST program gives and example of the use of KAFS. Note
  56. that this program also uses the SORT module. To compile this
  57. application you must compile KATEST.C, KAFS.C, and SORT.C and
  58. link to obtain the executable KATEST.EXE. Take a look at the
  59. program and run the executable. This will give you a good
  60. representation of how you can use KAFS and SORT.
  61.  
  62. Note also how the 'sizeof' function is used to determine record sizes.
  63.  
  64. How  KAFS Works
  65. See Production System Documentation .....
  66.  
  67.  
  68. Record Hashing Explained
  69. See Production System Documentation .....
  70.  
  71.  
  72. Hash Blocks and Overflows
  73. See Production System Documentation .....
  74.  
  75.  
  76. Using KAFS on Networks
  77. See Production System Documentation .....
  78.  
  79.  
  80. The KAUTIL Program
  81. The KAUTIL program is a key element in the KAFS system. All KAFS
  82. files must be created and initialized with this program before
  83. they can be used by your 'C' program. KAFS filenames are any 8
  84. characters (NO EXTENSIONS) that would be allowed as DOS
  85. filenames. All KAFS files have the extension KAF. A KAFS
  86. filename has NO EXTENSION.
  87.  
  88. Create & Initialize - Use this function to create and initialize
  89. KAFS files. You may also use this function to re initialize
  90. files (be careful).
  91.  
  92. File Status - Display's a KAFS file's current status.
  93.  
  94. File Re Size - Allows you to re size (smaller or larger) a KAFS
  95. file. Use Caution.
  96.  
  97. Record Dump - Dumps a record in 'byte' format.
  98.  
  99. Directory Check - Looks for KAFS files in the designated
  100. directory.
  101.  
  102. See Production System Documentation .....
  103.  
  104.  
  105. Steps to Using the KAFS Package
  106. Define record layouts in your 'C' program and determine record
  107. sizes. (Use 'sizeof' function)
  108.  
  109. Use the Create & Initialize function in KAUTIL to define and
  110. initialize each file.
  111.  
  112. Write your 'C' Code to open and access the files through KAFS.
  113. Include KAFS.C in your compilation and link process to create
  114. your executable. 
  115.  
  116. Execute, Test, and Debug your code.
  117.  
  118. KAFS, Version 2.0 - REGISTRATION
  119.  
  120.  
  121. Copyright 1991 - 1993, Dimestore Software All rights reserved
  122.  
  123.  
  124.  
  125. You can order or register Dimestore Software products by check
  126. or money order.
  127.  
  128.  
  129.  
  130. TO:                    FROM:
  131.  
  132. Dimestore Software         Name: _______________________________________
  133.  
  134. 23121 Verdugo Dr. Suite 202
  135.  
  136. Laguna Hills, CA 92653    (Company):_______________________________________
  137.  
  138.  
  139. 714-581-6749 Voice       (Title):_______________________________________
  140.  
  141.  
  142.                           Address: _______________________________________
  143.  
  144. Today's          
  145.  
  146. date: ___________     City, State:_______________________________________
  147.  
  148.                                                                     Zip Code
  149.  
  150.                      Phone Number: _____________________________
  151.  
  152.  
  153.  
  154. KAFS System  for MS-DOS
  155.  
  156.  
  157.   You will receive:
  158.  
  159.   1.  A full production Release of the product 
  160.   2.  A Printed Manual
  161.   3.  All Related Source Code (including KAUTIL)
  162.   4.  Source Code for DDWIN - Developer's Windows system
  163.  
  164.  
  165. Diskette format (choose one) 5.25" disk ____       3.5" disk ____
  166.  
  167.  
  168.     Diskette with programs and documentation files           $39.95
  169.  
  170.                              Shipping & handling              4.95
  171.  
  172. California residents add 7.75% sales tax    ($3.10)    
  173.  
  174.                                                 Total enclosed    ________
  175.  
  176.  
  177.  
  178. Terms:
  179.  
  180. Check or Money Order drawn on a USA Bank in US funds.  Corporate
  181. Purchase orders (net 30) accepted for software from large
  182. corporations within the USA & Canada.  All licenses must be prepaid.
  183.  
  184. Keyed Access File System Interface Specs
  185.  
  186.  
  187.  
  188. Global Definitions:
  189.  
  190. SOF -1                   (Start of File)
  191. OK  0                    ( Status is OK)
  192. ERR -1                   ( Status is Error Occurred )
  193. NOTFOUND  -2    ( Specified record was not found )
  194. FILEFULL -3     ( The file is full, no more records can be accepted )
  195. KAEOF -4         ( Key Access End of File Reached on Sequential Read )
  196.  
  197.  
  198.  
  199. Global Variables:
  200.  
  201. int rec;  - Current record number
  202. int kaerror;   - Error description value
  203. char *kaversion - Version number of KAFS
  204. char key[] - Holds key(string) of last record access or sets key
  205.              for next access
  206.  
  207.    
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  Key Access System Error Codes:
  214.  
  215. 1 File Already Open
  216. 2 Error Attempting to Open Hash Index
  217. 3 Error Attempting to Open Data File
  218. 4 File Not Open
  219. 5 Seek Error on Data File
  220. 6 Read Error on Data File
  221. 7 Write Error on Data File
  222. 8 Error Reading Hash Index Block
  223. 9 Error Writing Hash Index Block
  224. 10 Invalid File Number
  225. 11 Key Argument Exceeds Keysize
  226. 12 File Name Invalid
  227. 13 Rec Exceeds File's Extent
  228.  
  229. Keyed Access  Open, and Close Functions
  230.  
  231.  
  232.  
  233. ka_open(int filenumber, char *filename) - Opens the specified
  234. file as filenumber. Filename is a KAFS filname without extension.
  235.  
  236. RETURN: OK or ERR
  237.  
  238.  
  239.  
  240.  
  241.  
  242. ka_close(int filenumber) - Close the specified filenumber. 
  243.  
  244. RETURN: None
  245.  
  246.  
  247.  
  248.  
  249.  
  250. ka_close_all(void) - Closes all keyed access files.
  251.  
  252. RETURN: None
  253.  
  254.  
  255.  
  256.  
  257. filecommit(int filenumber) - Flush a file's data to disk. Used
  258. to insure file integrity.
  259.  
  260. RETURN: None
  261.  
  262.  
  263.  
  264. Keyed Access Read, Write, and Delete Functions
  265.  
  266.  
  267.  
  268. read_key(int filenumber,  char *key,  char *buffer)  -  If rec =
  269. SOF then the key is hashed and the read takes place.  If rec !=
  270. SOF  reads for a record based on the key field from the point of
  271. rec. If a match is found the record is read into the buffer
  272. specified. The 'rec' variable contains the record number.
  273.  
  274. RETURN: OK if record found, or NOTFOUND, or ERR
  275.  
  276.  
  277.  
  278.  
  279.  
  280. read_seq(int filenumber, char *buffer) - Reads the next record
  281. in the file.  Reads based on the value of 'rec'. (essentially
  282. rec + 1).  The next available record is returned regardless of
  283. the span in record numbers.  'rec' contains the record number if
  284. successful, and 'key' contains the key value.
  285.  
  286. RETURN: OK or KAEOF (end of file reached), or ERR
  287.  
  288.  
  289.  
  290. read_rec(int filenumber, char *buffer) - Reads the data portion
  291. of the record addressed by the value of rec. This function
  292. should only be used when the record has been previously read by
  293. either a read_key or a read_seq call. 'key' contains the key
  294. value.
  295.  
  296. RETURN: OK or ERR
  297.  
  298.  
  299.  
  300.  
  301.  
  302. write_key(int filenumber, char *key, void *buffer) - Writes a
  303. new record based on the hashcode of the key field. NO CHECKING
  304. FOR DUPLICATE RECORDS IS DONE.  Files may be written with
  305. multiple identical keys for records. 'key' must contain the
  306. record's key value. 'buffer' must contain the record's data
  307. record.
  308.  
  309. RETURN: OK if written, or ERR
  310.  
  311.  
  312.  
  313.  
  314.  
  315. write_upd(int filenumber, char *buffer) - Writes the data
  316. portion of the record back into the file. Essentially does a
  317. 'write_rec' of the data. Writes into the file based on the value
  318. of rec. Be sure 'rec' has not changed since read was performed
  319. (or reset 'rec').
  320.  
  321. RETURN: OK if written, or ERR
  322.  
  323.  
  324.  
  325.  
  326.  
  327. rdelete(int filenumber, long delrec) - Deletes a record.  The
  328. record to be deleted must have been previously read to obtain
  329. the correct record number.
  330.  
  331. RETURN: OK if deleted, or ERR
  332.