db-oracle/README

   1 This is the header of the cadabra source file.
   2
   3
   4 ;;;; a CMUCL/OCI implementation of a subset of the DBI interface
   5 ;;;;
   6 ;;;; The original version of this code was copyright (c) 1999-2000 Cadabra Inc.
   7 ;;;; It was placed in the public domain by Cadabra in January 2000.
   8 ;;;;
   9 ;;;; The implementors of the original version were Winton Davies
  10 ;;;; <wdavies@cadabra.com> and William Newman <william.newman@airmail.net>.
  11 ;;;; The code will be maintained by Winton Davies.
  12
  13 ;;;; known issues:
  14 ;;;;   * The code will leak C resources if errors occur in the the wrong
  15 ;;;;     places, since it doesn't wrap its allocation/deallocation
  16 ;;;;     logic in the necessary EVAL-WHENs to prevent this. (This could be
  17 ;;;;     easily be an issue for long-running processes which recover from
  18 ;;;;     database errors instead of simply terminating when they occur. It's
  19 ;;;;     not an issue for programs which consider database errors so abnormal
  20 ;;;;     that they die immediately when they encounter one.)
  21 ;;;;   * Instead of reading Oracle header files automatically, this code
  22 ;;;;     uses constants, types, and function signatures manually transcribed
  23 ;;;;     from the Oracle header files. Thus, changes in the header files
  24 ;;;;     may require manual maintenance of the code. (This version was written
  25 ;;;;     for Oracle 8.1.5.)
  26 ;;;;   * various KLUDGEs noted in the code
  27
  28 ;;;; log:
  29 ;;;;   6. * moved test suite to separate file
  30 ;;;;      * removed trailing spaces from all strings returned from database
  31 ;;;;      * fixed error in LIST-ALL-DATABASE-TABLES interface: DB should be
  32 ;;;;        a &KEY argument, not an &OPTIONAL argument
  33 ;;;;   7. * merged Winton's code to allow the SQL function to ask OCI
  34 ;;;;        whether an operation returns a table, and not to worry about
  35 ;;;;        the TYPE keyword argument if no table is returned
  36 ;;;;      * reduced +N-BUF-ROWS+ from 1000 to reduce probability of
  37 ;;;;        hitting CMUCL 18b 8Mb-of-C-data limit
  38 ;;;;      * changed NOT-USED argument of FETCH-ROW to EOF-ERRORP, to
  39 ;;;;        conform to Allegro interface
  40 ;;;;      * found apparent bug in OCI (wrong size of value returned for the
  41 ;;;;        +oci-attr-data-size+ attribute); added workaround
  42 ;;;;      * found and documented the unnecessariness of "workaround" for
  43 ;;;;        "WITH-ALIEN not working" (which was actually a conceptual error
  44 ;;;;        on WHN's part, expecting WITH-ALIEN to work the same way as
  45 ;;;;        MAKE-ALIEN, not expecting one less level of indirection)
  46 ;;;;      * cleaned up NULLS-OK-USE-THIS-ERRHP weirdness and inflexibility,
  47 ;;;;        splitting the one argument into separate NULLS-OK and ERRHP
  48 ;;;;        arguments
  49 ;;;;      * added :ERRHP optional arguments to various OERR expressions,
  50 ;;;;        so that now failures are more likely to generate informative
  51 ;;;;        error messages instead of just "OCI Error (and no ERRHP
  52 ;;;;        available to find subcode)"
  53 ;;;;   8. * added code to deallocate C resources
  54 ;;;;   9. * Added in an extra field for DATE-FORMAT and DATE-FORMAT-LENGTH
  55 ;;;;        Munged the code for datatype and colsize. Winton Davies.
  56 ;;;;  10. * cleaned up remnants of old date-is-fixed-length-field design
  57 ;;;;        assumption, getting rid of +OCi-date-bytes+
  58 ;;;;      * reduced consing in FETCH-ROW and associated functions
  59 ;;;;      * replaced WARN with IWARN for implementor-only warnings
  60 ;;;;  11. * fixed bad (THE (ALIEN (* FLOAT)) B) declaration for
  61 ;;;;        SQLT_FLT buffers (should be (ALIEN (* DOUBLE)) instead;
  62 ;;;;        and for some reason fell through the cracks of CMUCL's
  63 ;;;;        "declarations are assertions" principle)
  64 ;;;;      * deleted various FIXME notes a la "does this code ever get
  65 ;;;;        exercised?" and "are these really all the cases we need?"
  66 ;;;;      * changed the IWARN call to a KLUDGE comment, deleted IWARN
  67 ;;;;      * tidied up comments
  68 ;;;;      * changed page breaks from lots-of-semicolons Cadabra style
  69 ;;;;        to ^L CMUCL style
  70 ;;;;      * declared DBI-ERROR to be INLINE
  71 ;;;;      * fixed definition of +oci-htype-env+
  72 ;;;;      * reviewed and corrected C resource deallocation code
  73 ;;;;  12. * Made load-foreign depend on ORACLE-HOME for more portability.
  74