home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / classlib.zip / db.txt next >
Text File  |  1994-09-03  |  7KB  |  228 lines
  1. ===============================================================================
  2.   Objective C database library - classes to provide access to DBase III files
  3. ===============================================================================
  4.  
  5. 1. Introduction:
  6. ===============
  7.  
  8. This document describes a very simple database library to provide access to
  9. DBase III files. At the moment only methods to read and write records are
  10. provided.
  11.  
  12. Don't use this library at all. It has been only included with the OS/2 PM
  13. library for demonstration purpose. All classes and methods are subject to
  14. change.
  15.  
  16. Here only the classes and methods used in one of the demonstration programs
  17. for the PM library are described.
  18.  
  19. Future releases will accompany the PM library and provide a better support for
  20. all existing DBase III data types. Index files (BTree and maybe Hash) will
  21. be supported.
  22.  
  23. The version number of this library is 0.3
  24.  
  25. 2. Classes:
  26. ==========
  27.  
  28. The following classes are documented:
  29.  
  30.     *    DBFile        class for access to DBase data files
  31.     *    DBField        record data is stored in one or more fields
  32.     *    DBList        a list of records
  33.     *    DBRecord    a storage buffer to a record used in DBList
  34.  
  35. Before using any of the classes include <db/db.h>. This file includes all
  36. necessary Objective C Interface Files for the database classes.
  37.  
  38. 2.1 DBFile:
  39. ----------
  40.  
  41. Every DBase data file used is represented by an instance of DBFile.
  42.  
  43.  
  44. Methods:
  45.     - init: (char *) fileName
  46.         This function opens an existing DBase III data file and
  47.         generates the field structure in memory.
  48.  
  49.     - free
  50.         'free' closes the file and frees the field structure allocated
  51.         by 'init:'.
  52.  
  53.     - field: (int) fieldNumber
  54.         'field:' returns a pointer to an object of type DBField
  55.         (or one of its subclasses) associated with the data field
  56.         'fieldNumber'. The first data field has number 0.
  57.  
  58.     - readRecord: (long) offset
  59.         Read the record specified by 'offset'. The first record
  60.         has number 0.
  61.  
  62.     - append
  63.         Append a record to the data file. Data to store can be set
  64.         via the methods of DBField.
  65.  
  66.     - replace
  67.         Replace the current record with the information stored in
  68.         the instances of DBField.
  69.  
  70.     - delete
  71.         Delete the current record.
  72.  
  73.     - clear
  74.         Clear the data stored in the DBFields. This should always
  75.         be done before storing new data in the DBFields.
  76.  
  77. 2.2 DBField:
  78. -----------
  79.  
  80. Each of the data fields is represented by an instance of DBField or one
  81. of its subclasses. These objects are created by 'init:' of DBFile.
  82.  
  83.  
  84. Methods:
  85.     - setString: (char *) aString
  86.         This method stores 'aString' as the data of the DBField.
  87.         This method does not change the data file on disk.
  88.  
  89.     - (char *) string
  90.         'string' returns a pointer to the stored data of the DBField.
  91.  
  92. 2.3 DBList:
  93. ----------
  94.  
  95. A DBList can store a list of records retrieved from a DBFile.
  96.  
  97.  
  98. Methods:
  99.     - initForDatabase: (DBFile *) aDatabase
  100.         This method creates a new instance of DBList for a DBFile
  101.         previously created. 'aDatabase' is a pointer to this DBFile
  102.         object.
  103.  
  104.     - fetchAllRecords
  105.         Read all records which are not marked as deleted and insert
  106.         them into the DBList. Before fetching all records of the
  107.         DBList are deleted.
  108.  
  109.     - (int) count
  110.         'count' returns the number of records stored in the DBList
  111.         object.
  112.  
  113.     - findRecordAt: (int) index
  114.         'findRecordAt:' returns a pointer to the DBRecord object
  115.         at index 'index', or nil if 'index' is out of range.
  116.  
  117.     - insertRecord: (DBRecord *) aRecord
  118.         By calling this method, the DBRecord object 'aRecord' is
  119.         inserted at the end of the list.
  120.  
  121.     - deleteRecordAt: (int) index
  122.         This method deletes the DBRecord at index 'index'.
  123.  
  124.  
  125. 2.4 DBRecord:
  126. ------------
  127.  
  128. An instance of this class can store exactly one record of a DBase data file.
  129.  
  130.  
  131. Methods:
  132.     - initForDatabase: (DBFile *) aDatabase
  133.         This methods initializes a new DBRecord object for DBFile
  134.         'aDatabase'. The current record of this data file is copied
  135.         to the DBRecord data buffer.
  136.  
  137.     - copyToDB
  138.         This method copies the information stored in the DBRecord
  139.         object to the DBFile data buffer. There it can be modified
  140.         using DBFields.
  141.  
  142.     - copyFromDB
  143.         This method copies the data in the DBFile data buffer to
  144.         the DBRecord data buffer.
  145.  
  146.     - replace
  147.         This method writes the data buffer of the DBRecord to the
  148.         data file. The data buffer is stored to the record position
  149.         active at creation of the DBRecord object.
  150.  
  151.  
  152. 3. Future perspectives:
  153. ======================
  154.  
  155.     *    better support for all DBase III data types
  156.     *    indexing (BTree, maybe Hash)
  157.     *    more flexible DBList
  158.     *    PM classes supporting this library (fetch and display via a
  159.         multi-column listbox, simple storing of data, entryfields
  160.         directly communicating with database,...)
  161.     *    Database Creator to create empty data files.
  162.     *    much better documentation, sample programs
  163.     *    maybe a DLL version of the library.
  164.     *    ...
  165.  
  166.  
  167. 4. Licensing:
  168. ============
  169.  
  170. This library is distributed as a part of the accompanying OS/2 PM class
  171. library. Just register the PM class library to be allowed to use the DBase
  172. class library.
  173.  
  174. After registration you are automatically registered for all following versions
  175. of the library until the major version number increases. That means by
  176. registering this version of the library together with the PM class library
  177. (PM library: version 0.5; DB library: version 0.3) you are automatically
  178. registered for all future versions of the DB library including version
  179. 1.0.
  180.  
  181. Starting at version 1.1 of the DB library you have to register newly at a
  182. special update price.
  183.  
  184. Support the Shareware distribution concept and register if you like this
  185. library and want to use it in your own applications. Future Shareware
  186. releases of this library depend heavily on the will of users to register.
  187. So, if no one registers this library, surely no further effort will be made
  188. in adding functionality to the library.
  189.  
  190.  
  191. 5. Warranty:
  192. ===========
  193.  
  194. Well, as you might have thought, there's ABSOLUTELY NO WARRANTY for this
  195. library package.
  196.  
  197.  
  198. 6. Pricing:
  199. ==========
  200.  
  201. The registration fee for the OS/2 PM class library together with the Database
  202. library is 250ATS (250 Austrian Schillings), that's about 25US$, per copy
  203. for individuals or 500ATS for companies. Don't forget to check with your bank,
  204. how much you should pay, so that I will get the whole registration fee as
  205. mentioned above.
  206.  
  207. Don't forget to fill in the registration form and send it to me (address
  208. below).
  209.  
  210. -------------------------------------------------------------------------------
  211.  
  212. Send the money directly to my local bank account:
  213.  
  214.     NAME OF BANK:         RAIFFEISENBANK KREMS
  215.     ID Nr. OF BANK:        32397
  216.     ACCOUNT NR.:        12.195
  217.  
  218. For information about 10+ licenses of this libraries feel free to contact
  219. me via Internet E-Mail (baier@ci.tuwien.ac.at) or via Snail Mail at:
  220.  
  221. Thomas Baier
  222. Ufergasse 68
  223. A-3500 Krems
  224. Austria
  225.  
  226. Internet: baier@ci.tuwien.ac.at
  227.  
  228.