
   #[1]next [2]previous [3]up [4]next
   
   [5]next [6]up [7]previous [8]contents 
   Next: [9]3. Important Changes Up: [10]Introductory Material Previous:
   [11]1. Introduction   [12]Contents
   Subsections
     * [13]The Main Database Handle
     * [14]The Query Object
     * [15]The Result Sets
          + [16]The Dramatic Result Set
          + [17]The Static Result Sets
          + [18]The Dynamic Fully Mutable Sets
     * [19]In addition
     _________________________________________________________________
   
                                  2. Overview
                                       
   The Mysql++ API has developed into a very complex and powerful being.
   With many different ways to accomplish the same task. Unfortunately
   this means that figuring out how to perform a simple task can be
   frustrating for new users of my library. In this section we will
   attempt to provide an overview of the many different components of the
   library.
   
   Like working with most other SQL API the process for executing queries
   is the same. 1) You open the connection, 2) You form and execute the
   queries, 3) You iterate through the result set. It not much different
   in my C++ API. However there is a lot of extra functionality along
   each step of the way.
   
                           The Main Database Handle
                                       
   This is a class that handles the connection to the Mysql server. You
   always need at least one of these objects to do anything. It can
   either create a separate queries object or directly execute queries.
   The separate query object is the recommended way as it gives you far
   more power.
   
                               The Query Object
                                       
   This object is the recommended way of executing queries. It is
   subclassed from strstream which means you can write to it like any
   other stream to aid in the formation of queries.
   
   You can also set up Template queries with this class. Template queries
   are a way of setting up queries with replaceable parameters that you
   can change throughout your program.
   
   You can also use specialized structures and even the dramatic result
   sets to aid in creating queries however more on that latter.
   
   The Query object returns an object with information about the success
   of a query for non-select queries (queries that don't return a result
   set).
   
                                The Result Sets
                                       
   For queries that return a result set you have essentially two
   different ways of handling the results: in a dramatic result set, or
   in a static one.
   
The Dramatic Result Set

   The Dramatic Result set is a result set in which the names of the
   columns and the type of information of the columns does not need to be
   determined at compile time. The result set can be completely constant
   in which the data is returned to you in a constant string link class,
   semi-constant in which you can modify the data one row at a time, or a
   truly mutable in which in you can modify the data in any way you like.
   
   The constant result set is a result set that is closely bound to the
   result set in the C API and is the one that provides the most
   functionality. With this result set you can find out detailed
   information about the type of information stored in each of the
   columns. This is also the fastest because the data does not need to be
   copied at all.
   
   The semi-constant result set is like the constant result set except
   you can modify the data one row at a time. The data you modify is
   actually a copy of the data returned by the server. This means that
   modifying the data does not change the actual result set at all.
   
   The semi-constant result set is actually the same thing as the
   constant result set. The only difference is that when you request a
   row from the result set you specifically declare the row as a mutable
   one. This means that you can get some rows back as constant rows and
   others as mutable ones.
   
   The truly mutable result set is a result set similar to the constant
   one except that the data is truly mutable in the sense that you can
   change the data in the actual result set. However unlike the first one
   this result set is not bound to the C API result set. Instead it
   containers a copy of the data returned by the C API in a
   two-dimensional vector. Because of this the detailed information about
   each of the columns is not currently available, only the column names
   and the C++ type that most closely matches the original SQL type.
   Also, because it makes a copy of the data returned from the C API,
   there is a little bit of performance penalty to using this one.
   
   The rows in all the dramatic result sets are very close to an Standard
   Template Library (STL) random access container. This means that they
   have an iterator which can be used for STL algorithms. There is even
   couple of specialized utility function to aid in the use of the result
   sets in STL algorithms.
   
   The columns in all the dramatic result are also very close to an STL
   random access container. However, in addition to accessing the columns
   by there index number you can also access the columns via there field
   names.
   
   In addition, because both the rows and the columns are STL like
   containers, you can also treat the result set as a two- dimensional
   array. For example you can get the 5th item on the 2nd row by simply
   saying result[2][5]. Because you can also use the field names you can
   substitute the column number by a field name and say
   result[2]["price"] to get "price" of the item on the 2nd row, for
   example.
   
   The actual data that all the dramatic result sets return is stored in
   a special string like class that has some additional magic too it. The
   magic is that the column data will automatically convert itself into
   all of the basic data types as well as some additional types types
   that are designed to handle mysql types which includes types for
   handling dates, times, sets, and types with a null value. If there is
   a problem in the conversion it will either set a warning flag or throw
   an exception depending on how it is configured. Regarding exceptions,
   MySQL++ supports two different methods of tracing exceptions. One is
   by the fixed type (the old one) and one is standard C++ type by the
   usage of what() method. A choice of methods has to be done in building
   a library. If configure script is run with -enable-exception option ,
   then new method will be used. If no option is provided, or
   -disable-exception is used, old MySQL++ exceptions will be enforced.
   
   The drastic result sets can even be used to help form queries with the
   help of some additional method. There is a method for returns: 1) A
   comma separated list of the data (for example: 1.5, 10, "Dog,
   "Brown"), 2) A comma separated list of the field names (for example:
   age, weight, what, color), and 3) An equal list (for example: age =
   1.5 AND weight = 10 AND what = "Dog" AND color = "Brown").
   
   Mutable result sets can be created with out an actual query so that
   you can take advantage of these methods to aid in inserting data into
   the database with out having to first create an unnecessary query.
   
The Static Result Sets

   The results from an query can also be stored statically in what we
   call a specialized SQL structure. These structures are then stored in
   some STL container such a vector or list, or even a set or multi-set
   as the the specialized structures can also be made
   less-than-comparable. Unlike the dramatic result sets it is assumed
   that the programmer knows what the result set is going to look like.
   Because of this all the information about the columns, including the
   names, are lost.
   
   These Specialized Structures are exactly that C++ `structs'. Each
   member item is stored with a unique name within the structure. You can
   in no way use STL algorithms or anything else STL to work with the
   individual elements of the structures. However naturally because these
   structures are then stored in STL containers you can use STL
   algorithms on the containers of these structures. The containers
   represent the rows, and the individual elements of the structure
   represent the columns. For example you can access the item named
   "price" on the second row by saying result[2].price. With the dramatic
   result set you would have probably needed to say result[2]["price"] to
   accomplish the same result.
   
   If there is a problem in converting from the result set returned by
   the server to the specialized structures an exception is thrown.
   
   To aid in the creating of queries using these specialized structures,
   the same query aiding methods are available to use that are available
   for the dramatic result sets. This includes methods for returning a
   comma separated list of the data, a comma separated list of the field
   names, and an equal list.
   
The Dynamic Fully Mutable Sets

   This result set will be implemented when server-side cursors are
   implemented in MySQL. But, based on so far acquired knowledge and
   experience, from designing and implementing both MySQL++ and MySQLGUI,
   a preliminiary layout and design of the most advanced result set so
   far has been achieved. It's implementation is postponed, however, from
   the above reasons. This result set will be fully dynamic and dramatic.
   This result set is fully dynamic in a sense that entire result set is
   stored in a dynamic C++ container. This container will be only a cache
   , a dynamic cache, to the entire result set, and will have a default
   size. This dynamic container will be a window of M rows into an entire
   result set of N rows, where N is limited by MySQL server , Operating
   System and File System only. This result set will also be fully
   dramatic in a sense that the names of the columns and the type of
   information of the columns will not need to be determined at compile
   time. But all existing functionality of static , mutable sets will be
   available in this set too. However as this set will be dramatic, no
   advance information on result set structure will be necessary, which
   will thus aleviate need for the usage of specialized macros for the
   construction of classes. This set will also have methods for updating,
   deleting and inserting rows in a manner that will be almost identical
   for use as methods for the existing fully mutable sets.
   
                                  In addition
                                       
   In addition to the material mentioned there are also many generic
   classes that can be used with other programs. Examples of this include
   a special const string class, a const random access adapter that will
   make a random access container out of a class with nothing but the
   size() method and the subscript ([]) operator defined and a generic
   SQL query class that can be used any SQL C or C++ API.
   
   As from version 1.7, there is a new addtion to the libraries. Several
   very usefull functions for STL strings can be added, which can be used
   in any C++ aplication, MySQL++ related or not. Those functions are
   contained in source files string_util.hh and string_util.cc.
     _________________________________________________________________
   
   [20]next [21]up [22]previous [23]contents 
   Next: [24]3. Important Changes Up: [25]Introductory Material Previous:
   [26]1. Introduction   [27]Contents
   
   
    2001-05-01

References

   1. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
   2. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/1_Introduction.html
   3. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Introductory_Material.html
   4. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
   5. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
   6. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Introductory_Material.html
   7. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/1_Introduction.html
   8. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Contents.html
   9. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
  10. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Introductory_Material.html
  11. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/1_Introduction.html
  12. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Contents.html
  13. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02210000000000000000
  14. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02220000000000000000
  15. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02230000000000000000
  16. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02231000000000000000
  17. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02232000000000000000
  18. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02233000000000000000
  19. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/2_Overview.html#SECTION02240000000000000000
  20. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
  21. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Introductory_Material.html
  22. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/1_Introduction.html
  23. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Contents.html
  24. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/3_Important.html
  25. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Introductory_Material.html
  26. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/1_Introduction.html
  27. file://localhost/home/Sinisa/mysql++-1.7/doc/man-html/Contents.html
