[libgda] Misc doc. corrections
- From: Vivien Malerba <vivien src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [libgda] Misc doc. corrections
- Date: Mon, 5 Oct 2009 18:46:44 +0000 (UTC)
commit 85f9aa5e468aec4e626ebbb80a35cbda927b07c4
Author: Vivien Malerba <malerba gnome-db org>
Date: Mon Oct 5 20:40:03 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 | 12 +++++++++---
4 files changed, 46 insertions(+), 6 deletions(-)
---
diff --git a/doc/C/libgda-4.0-docs.sgml b/doc/C/libgda-4.0-docs.sgml
index 82951ef..60adabb 100644
--- a/doc/C/libgda-4.0-docs.sgml
+++ b/doc/C/libgda-4.0-docs.sgml
@@ -508,6 +508,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 b73909c..69ba8bb 100644
--- a/libgda/gda-connection.c
+++ b/libgda/gda-connection.c
@@ -2317,8 +2317,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 d55f31a..effb9c6 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 bc21ce1..9dc7b76 100644
--- a/libgda/sqlite/gda-sqlite-blob-op.c
+++ b/libgda/sqlite/gda-sqlite-blob-op.c
@@ -104,7 +104,9 @@ gda_sqlite_blob_op_finalize (GObject * object)
/* free specific information */
if (bop->priv->sblob) {
sqlite3_blob_close (bop->priv->sblob);
- /* g_print ("CLOSED blob %p\n", bop); */
+#ifdef GDA_DEBUG_NO
+ g_print ("CLOSED blob %p\n", bop);
+#endif
}
g_free (bop->priv);
bop->priv = NULL;
@@ -158,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;
@@ -166,7 +170,9 @@ _gda_sqlite_blob_op_new (SqliteConnectionData *cdata,
bop = g_object_new (GDA_TYPE_SQLITE_BLOB_OP, NULL);
bop->priv->sblob = sblob;
- /* g_print ("OPENED blob %p\n", bop); */
+#ifdef GDA_DEBUG_NO
+ g_print ("OPENED blob %p\n", bop);
+#endif
out:
if (free_strings) {
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]