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.
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
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
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
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.
Because you can also use the field names you can substitute the column
number by a field name and say result["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 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.price. With the dramatic
result set you would have probably needed to say result["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.
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 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.