[libgda/LIBGDA_4.0] Misc doc. corrections

[Vivien Malerba <vivien src gnome org>]

commit 45c92d847c1d0120367e220e4c5788edfb704298
Author: Vivien Malerba <malerba gnome-db org>
Date:   Mon Oct 5 20:46:18 2009 +0200

    Misc doc. corrections

 doc/C/libgda-4.0-docs.sgml         |   28 ++++++++++++++++++++++++++++
 libgda/gda-connection.c            |   10 ++++++++--
 libgda/gda-util.c                  |    2 +-
 libgda/sqlite/gda-sqlite-blob-op.c |   13 +++++++++++--
 4 files changed, 48 insertions(+), 5 deletions(-)
---
diff --git a/doc/C/libgda-4.0-docs.sgml b/doc/C/libgda-4.0-docs.sgml
index 7f6f8b1..23b2e9e 100644
--- a/doc/C/libgda-4.0-docs.sgml
+++ b/doc/C/libgda-4.0-docs.sgml
@@ -475,6 +475,34 @@
 	  </mediaobject>
 	</para>
       </sect1>
+
+      <sect1 id="gen:blobs">
+	<title>Binary large objects (BLOBs)</title>
+	<para>
+	  Binary large objects (BLOBs) are potentially very big (serevral GigaBytes) pieces of binary
+	  data which databases can store. Because of their potential size, they are not manipulated
+	  like any other data, and are usually not transfered when running a statement: first
+	  a reference to a blob is created for an existing or a new blob using a statement, and then
+	  that reference is used, <emphasis>after the statement has been executed</emphasis>, to
+	  get or set some parts of the blob.
+	</para>
+	<para>
+	  &LIBGDA; makes its best to hide the complexity of this and most of the time blobs can be used
+	  like any other type of values with the following limitations:
+	  <itemizedlist>
+	    <listitem><para>When getting a blob through a SELECT statement, a transaction will automatically
+		be started if it's not already started, and usually the transaction (implicitly or explicitly)
+		will be locked untill all the ressources associated to the fetched blobs are liberated (by
+		calling <link linkend="g-object-unref">g_object_unref()</link> on the model).</para></listitem>
+	    <listitem><para>When fetching a blob value (using
+		<link linkend="gda-data-model-get-value-at()">gda_data_model_get_value_at()</link> for example), the blob
+		itself is not fetched, only a reference to the blob is fetched, and one has to use the
+		<link linkend="GdaBlobOp">GdaBlobOp</link> object embedded in a blob value to get the blob's
+		contents.</para></listitem>
+	  </itemizedlist>
+	</para>
+      </sect1>
+
     </chapter>
 
     &howto;
diff --git a/libgda/gda-connection.c b/libgda/gda-connection.c
index e9846eb..ec2d580 100644
--- a/libgda/gda-connection.c
+++ b/libgda/gda-connection.c
@@ -1705,8 +1705,14 @@ gda_connection_statement_execute_v (GdaConnection *cnc, GdaStatement *stmt, GdaS
  * then the resulting data model will re-run itself, see the GdaDataSelect's 
  * <link linkend="GdaDataSelect--auto-reset">auto-reset</link> property for more information.
  *
- * Note4: if @model_usage does not contain the GDA_STATEMENT_MODEL_RANDOM_ACCESS or GDA_STATEMENT_MODEL_CURSOR_FORWARD
- * flags, then the default will be to return a random access data model
+ * Note4: if @model_usage does not contain the GDA_STATEMENT_MODEL_RANDOM_ACCESS or
+ * GDA_STATEMENT_MODEL_CURSOR_FORWARD flags, then the default will be to return a random access data model
+ *
+ * Note5: If @stmt is a SELECT statement which returns blob values (of type %GDA_TYPE_BLOB), then an implicit
+ * transaction will have been started by the database provider, and it's up to the caller to close the transaction
+ * (which will then be locked) once all the blob ressources have been
+ * liberated (when the returned data model is destroyed). See the section about
+ * <link linkend="gen:blobs">Binary large objects (BLOBs)</link> for more information.
  *
  * Also see the <link linkend="limitations">provider's limitations</link>, and the
  * <link linkend="data-select">Advanced GdaDataSelect usage</link> sections.
diff --git a/libgda/gda-util.c b/libgda/gda-util.c
index cb79652..eabae01 100644
--- a/libgda/gda-util.c
+++ b/libgda/gda-util.c
@@ -113,7 +113,7 @@ gda_g_type_to_string (GType type)
  *   <listitem><para>"null" for GDA_TYPE_NULL</para></listitem>
  * </itemizedlist>
  *
- * Returns: the #GType represented by the given @str.
+ * Returns: the #GType represented by the given @str, or #G_TYPE_INVALID if not found
  */
 GType
 gda_g_type_from_string (const gchar *str)
diff --git a/libgda/sqlite/gda-sqlite-blob-op.c b/libgda/sqlite/gda-sqlite-blob-op.c
index 9ae0e8f..9dc7b76 100644
--- a/libgda/sqlite/gda-sqlite-blob-op.c
+++ b/libgda/sqlite/gda-sqlite-blob-op.c
@@ -102,8 +102,12 @@ gda_sqlite_blob_op_finalize (GObject * object)
 	g_return_if_fail (GDA_IS_SQLITE_BLOB_OP (bop));
 
 	/* free specific information */
-	if (bop->priv->sblob)
+	if (bop->priv->sblob) {
 		sqlite3_blob_close (bop->priv->sblob);
+#ifdef GDA_DEBUG_NO
+		g_print ("CLOSED blob %p\n", bop);
+#endif
+	}
 	g_free (bop->priv);
 	bop->priv = NULL;
 
@@ -156,7 +160,9 @@ _gda_sqlite_blob_op_new (SqliteConnectionData *cdata,
 				1, /* Read & Write */
 				&(sblob));
 	if (rc != SQLITE_OK) {
-		/*g_print ("ERROR: %s\n", sqlite3_errmsg (cdata->connection));*/
+#ifdef GDA_DEBUG_NO
+		g_print ("ERROR: %s\n", sqlite3_errmsg (cdata->connection));
+#endif
 		if (transaction_started)
 			gda_connection_rollback_transaction (cdata->gdacnc, NULL, NULL);
 		goto out;
@@ -164,6 +170,9 @@ _gda_sqlite_blob_op_new (SqliteConnectionData *cdata,
 
 	bop = g_object_new (GDA_TYPE_SQLITE_BLOB_OP, NULL);
 	bop->priv->sblob = sblob;
+#ifdef GDA_DEBUG_NO
+	g_print ("OPENED blob %p\n", bop);
+#endif
 
  out:
 	if (free_strings) {