Merge lp:~linuxjedi/libdrizzle/5.1-docs into lp:libdrizzle

[Andrew Hutchings]

Update the docs for the latest prep statement changes

Also bump version ready for release soon

[lp:~linuxjedi/libdrizzle/5.1-docs]

80. By Andrew Hutchings on 2013-01-04

Fix spec.in for lib version

=== modified file 'configure.ac'
--- configure.ac	2012-12-29 17:31:57 +0000
+++ configure.ac	2013-01-04 21:00:30 +0000
@@ -6,7 +6,7 @@
 # Use and distribution licensed under the BSD license.  See
 # the COPYING file in this directory for full text.
 
-AC_INIT([libdrizzle],[5.1.0],[http://bugs.launchpad.net/drizzle],[libdrizzle],[http://drizzle.org/])
+AC_INIT([libdrizzle],[5.1.1],[http://bugs.launchpad.net/drizzle],[libdrizzle],[http://drizzle.org/])
 
 AC_CONFIG_AUX_DIR([build-aux])
 
@@ -27,7 +27,7 @@
 AC_CONFIG_SRCDIR([libdrizzle/drizzle.cc])
 
 #shared library versioning
-LIBDRIZZLE_LIBRARY_VERSION=5:1:0
+LIBDRIZZLE_LIBRARY_VERSION=6:0:0
 #                         | | |
 #                  +------+ | +---+
 #                  |        |     |
 
=== modified file 'docs/api/connection.rst'
--- docs/api/connection.rst	2012-12-22 08:54:15 +0000
+++ docs/api/connection.rst	2013-01-04 21:00:30 +0000
@@ -215,6 +215,13 @@
    :param con: A connection object
    :returns: A :c:type:`drizzle_return_t` status.  :py:const:`DRIZZLE_RETURN_OK` upon success
 
+.. c:function:: drizzle_return_t drizzle_close(drizzle_st *con)
+
+   Gracefully disconnect from a server (leaves the connection object available for a reconnect
+
+   :param con: A connection object
+   :returns: A :c:type:`drizzle_return_t` response for the quit command sent to the server
+
 .. c:function:: drizzle_return_t drizzle_quit(drizzle_st *con)
 
    Gracefully disconnect from a server and free the connection object
 
=== modified file 'docs/api/statement.rst'
--- docs/api/statement.rst	2012-12-23 14:44:44 +0000
+++ docs/api/statement.rst	2013-01-04 21:00:30 +0000
@@ -19,17 +19,108 @@
    :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into
    :returns: A newly allocated and prepared statement object (or NULL on error)
 
-.. c:function:: drizzle_return_t drizzle_stmt_bind_param(drizzle_stmt_st *stmt, uint16_t param_num, drizzle_column_type_t type, void *data, uint32_t length, drizzle_bind_options_t options)
-
-   Bind a parameter to send in statement.  This needs to be called before every
-   :c:func:`drizzle_stmt_execute` if the data changes.
-
-   :param stmt: The prepared statement object
-   :param param_num: The parameter number this bind is for
-   :param type: The column type this parameter uses
-   :param data: The data for this parameter
-   :param length: The length of the data
-   :param options: Options for the parameter
+.. c:function:: drizzle_return_t drizzle_stmt_set_tiny(drizzle_stmt_st *stmt, uint16_t param_num, uint8_t value, bool is_unsigned)
+
+   Sets a parameter of a prepared statement to a tinyint value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :param is_unsigned: Set to true if the parameter is unsigned
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_short(drizzle_stmt_st *stmt, uint16_t param_num, uint16_t value, bool is_unsigned)
+
+   Sets a parameter of a prepared statement to a short int value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :param is_unsigned: Set to true if the parameter is unsigned
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_int(drizzle_stmt_st *stmt, uint16_t param_num, uint32_t value, bool is_unsigned)
+
+   Sets a parameter of a prepared statement to an int value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :param is_unsigned: Set to true if the parameter is unsigned
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_bigint(drizzle_stmt_st *stmt, uint16_t param_num, uint64_t value, bool is_unsigned)
+
+   Sets a parameter of a prepared statement to a bigint value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :param is_unsigned: Set to true if the parameter is unsigned
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_double(drizzle_stmt_st *stmt, uint16_t param_num, double value)
+
+   Sets a parameter of a prepared statement to a double value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_float(drizzle_stmt_st *stmt, uint16_t param_num, float value)
+
+   Sets a parameter of a prepared statement to a float value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_string(drizzle_stmt_st *stmt, uint16_t param_num, char *value, size_t length)
+
+   Sets a parameter of a prepared statement to a string value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param value: The value to set the parameter
+   :param length: The length of the value data
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_null(drizzle_stmt_st *stmt, uint16_t param_num)
+
+   Sets a parameter of a prepared statement to a NULL value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_time(drizzle_stmt_st *stmt, uint16_t param_num, uint32_t days, uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t microseconds, bool is_negative)
+
+   Sets a parameter of a prepared statement to a time value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param days: The number of days for the time
+   :param hours: The number of hours for the time
+   :param minutes: The number of minutes for the time
+   :param seconds: The number of seconds for the time
+   :param microseconds: The number of microseconds for the time
+   :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
+
+.. c:function:: drizzle_return_t drizzle_stmt_set_timestamp(drizzle_stmt_st *stmt, uint16_t param_num, uint16_t year, uint8_t month, uint8_t day, uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t microseconds)
+
+   Sets a parameter of a prepared statement to a datetime/timestamp value
+
+   :param stmt: A prepared statement object
+   :param param_num: The parameter number to set (starting at 0)
+   :param year: The year number for the timestamp
+   :param month: The month number for the timestamp
+   :param day: The day number for the timestamp
+   :param hours: The hour number for the timestamp
+   :param minutes: The minute number for the timestamp
+   :param seconds: The minute number for the timestamp
+   :param microseconds: The minute number for the timestamp
    :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
 
 .. c:function:: drizzle_return_t drizzle_stmt_execute(drizzle_stmt_st *stmt)
@@ -71,6 +162,61 @@
    :param stmt: The prepared statement object
    :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
 
+.. c:function:: bool drizzle_stmt_get_is_null(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)
+
+   Check if a column for a fetched row is set to NULL
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into
+   :returns: True if NULL
+
+.. c:function:: bool drizzle_stmt_get_is_unsigned(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)
+
+   Check if a column for a fetched row is unsigned
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into
+   :returns: True if unsigned
+
+.. c:function:: const char *drizzle_stmt_get_string(drizzle_stmt_st *stmt, uint16_t column_number, size_t *len, drizzle_return_t *ret_ptr)
+
+   Get the string value for a column of a fetched row (int types are automatically converted)
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param len: A pointer to a :c:type:`size_t` to store the result length into
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into
+   :returns: A pointer to the string value
+
+.. c:function:: uint32_t drizzle_stmt_get_int(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)
+
+   Get the int value for a column of a fetched row
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into :py:const:`DRIZZLE_RETURN_TRUNCATED` if a truncation has occurred
+   :returns: The int value
+
+.. c:function:: uint64_t drizzle_stmt_get_bigint(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)
+
+   Get the bigint value for a column of a fetched row
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into :py:const:`DRIZZLE_RETURN_TRUNCATED` if a truncation has occurred
+   :returns: The bigint value
+
+.. c:function:: double drizzle_stmt_get_double(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)
+
+   Get the double value for a column of a fetched row
+
+   :param stmt: The prepared statement object
+   :param column_number: The column number to get (starting at 0)
+   :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into :py:const:`DRIZZLE_RETURN_TRUNCATED` if a truncation has occurred
+   :returns: The double value
+
 .. c:function:: drizzle_return_t drizzle_stmt_close(drizzle_stmt_st *stmt)
 
    Close and free a prepared statement
@@ -78,38 +224,6 @@
    :param stmt: The prepared statement object
    :returns: A return status code, :py:const:`DRIZZLE_RETURN_OK` upon success
 
-.. c:function:: drizzle_column_type_t drizzle_stmt_item_type(drizzle_stmt_st *stmt, uint16_t column_number)
-
-   Gets the column type of an element from a row retrieved with :c:func:`drizzle_stmt_fetch`
-
-   :param stmt: The prepared statement object
-   :param column_number: The column number for the element
-   :returns: The column type
-
-.. c:function:: void* drizzle_stmt_item_data(drizzle_stmt_st *stmt, uint16_t column_number)
-
-   Gets the data of an element from a row retrieved with :c:func:`drizzle_stmt_fetch`
-
-   :param stmt: The prepared statement object
-   :param column_number: The column number for the element
-   :returns: The data for the element
-
-.. c:function:: uint32_t drizzle_stmt_item_length(drizzle_stmt_st *stmt, uint16_t column_number)
-
-   Gets the length of the data for an element from a row retrieved with :c:func:`drizzle_stmt_fetch`
-
-   :param stmt: The prepared statement object
-   :param column_number: The column number for the element
-   :returns: The length of data for the element
-
-.. c:function:: drizzle_bind_options_t drizzle_stmt_item_options(drizzle_stmt_st *stmt, uint16_t column_number)
-
-   Gets the options set for an element from a row retrieved with :c:func:`drizzle_stmt_fetch`
-
-   :param stmt: The prepared statement object
-   :param column_number: The column number for the element
-   :returns: The options for the element
-
 .. c:function:: uint16_t drizzle_stmt_column_count(drizzle_stmt_st *stmt)
 
    Gets the column count for a result set which has been executed using :c:func:`drizzle_stmt_execute`
 
=== modified file 'docs/examples/statement.rst'
--- docs/examples/statement.rst	2012-12-23 14:44:44 +0000
+++ docs/examples/statement.rst	2013-01-04 21:00:30 +0000
@@ -12,8 +12,8 @@
 :c:func:`drizzle_stmt_prepare` and we can get the number of parameters the
 server is expecting with :c:func:`drizzle_stmt_param_count`.  In this example
 we know that there is only one parameter required so we send one INT type
-parameter using :c:func:`drizzle_stmt_bind_param` stating that this is
-parameter 0 and it is 4 bytes long (standard for an INT type).
+parameter using :c:func:`drizzle_stmt_set_int` stating that this is
+parameter 0 and a signed value.
 
 Once the parameters have been provided the statement is executed using
 :c:func:`drizzle_stmt_execute` and the results buffered using
@@ -22,11 +22,9 @@
 
 Finally we get the result data.  A call to :c:func:`drizzle_stmt_fetch` gets
 the next row from either the network or the buffer (the buffer in this case).
-The data can be retreived using :c:func:`drizzle_stmt_item_data`, a call for
-each column in the row (in example the table only has one column).
-
-It is also possible to get the data type and length of data using the other
-``drizzle_stmt_item_`` functions.
+The int data is retreived using :c:func:`drizzle_stmt_get_int`, a call for
+each column in the row (in example the table only has one column) is made using
+the ``drizzle_stmt_get_`` functions.
 
 When we are done the statement is closed and cleaned up using
 :c:func:`drizzle_stmt_close`.  It can also be reused with
@@ -45,7 +43,7 @@
   printf("Params: %" PRIu16 "\n", drizzle_stmt_param_count(stmt));
 
   uint32_t val= 1;
-  ret = drizzle_stmt_bind_param(stmt, 0, DRIZZLE_COLUMN_TYPE_LONG, &val, 4, DRIZZLE_BIND_OPTION_NONE);
+  ret = drizzle_stmt_set_int(stmt, 0, val, false);
 
   ret = drizzle_stmt_execute(stmt);
 
@@ -54,8 +52,8 @@
   printf("Rows found: %" PRIu64 "\n", drizzle_stmt_row_count(stmt));
   while (drizzle_stmt_fetch(stmt) != DRIZZLE_RETURN_ROW_END)
   {
-    uint32_t *res_val;
-    res_val= (uint32_t*)drizzle_stmt_item_data(stmt, 0);
+    uint32_t res_val;
+    res_val= drizzle_stmt_get_int(stmt, 0, &ret);
     printf("Got value: %" PRIu32 "\n", *res_val);
   }
   ret = drizzle_stmt_close(stmt);
 
=== modified file 'rpm/spec.in'
--- rpm/spec.in	2012-12-31 00:19:49 +0000
+++ rpm/spec.in	2013-01-04 21:00:30 +0000
@@ -53,8 +53,7 @@
 %{_libdir}/libdrizzle.a
 %{_libdir}/libdrizzle.la
 %{_libdir}/libdrizzle.so
-%{_libdir}/libdrizzle.so.5
-%{_libdir}/libdrizzle.so.5.0.1
+%{_libdir}/libdrizzle.so.*
 %{_bindir}/drizzle_binlogs
 %{_bindir}/libdrizzle-config