GNOME.org
 

[libgda/LIBGDA_4.2] Doc. improvements

commit 9cf6ba7b1393863f764d542904647999075421bd
Author: Vivien Malerba <malerba gnome-db org>
Date:   Wed Aug 31 18:48:20 2011 +0200

    Doc. improvements

 doc/C/Makefile.am          |    2 +-
 doc/C/abstraction.xml      |  119 ++++++++++++++++++++++++++++++++++++++++++++
 doc/C/libgda-4.0-docs.sgml |   89 +--------------------------------
 3 files changed, 122 insertions(+), 88 deletions(-)
---
diff --git a/doc/C/Makefile.am b/doc/C/Makefile.am
index 8100b4e..b6f6705 100644
--- a/doc/C/Makefile.am
+++ b/doc/C/Makefile.am
@@ -76,7 +76,7 @@ include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
 EXTRA_DIST += examples/full_example.c installation.xml limitations.xml migration.xml migration2.xml \
-	server-operation.xml gettingstarted.xml virtual.xml virtual-notice.xml store-meta-type.xml \
+	server-operation.xml gettingstarted.xml abstraction.xml virtual.xml virtual-notice.xml store-meta-type.xml \
 	prov-writing.xml packaging.xml packaging_ui.xml i_s_doc.xml howto.xml gda-sql-manual.xml data_validation.xml data_select.xml \
 	DataModels.svg \
 	architecture.svg parts.svg stmt-unknown.svg stmt-select.svg stmt-insert1.svg stmt-insert2.svg \
diff --git a/doc/C/abstraction.xml b/doc/C/abstraction.xml
new file mode 100644
index 0000000..5758462
--- /dev/null
+++ b/doc/C/abstraction.xml
@@ -0,0 +1,119 @@
+    <chapter>
+      <title>Foreword about abstraction</title>
+      <para>
+	&LIBGDA; aims both at making it easier to use databases and, for applications written using it, 
+	at making it easier to switch to a different database or to to be able to use different types of databases
+	with a minimum or no code modifications. To achieve the 2nd goal, &LIBGDA; proposes an abstraction of
+	most of database's engine features, which has to be understood to write portable code.
+      </para>
+
+      <sect1 id="placeholders">
+	<title>Variables syntax in SQL</title>
+	<para>
+	  Each database engine has its own way of specifying variables (i.e. place holders) in SQL code (for example:
+	  <code>$&lt;number&gt;</code>, <code>:&lt;name&gt;</code>, <code>?&lt;number&gt;</code>, or <code>?</code>).
+	  &LIBGDA; has specified yet another format for variables which can be used with all the databases and which
+	  has the following advantages:
+	  <itemizedlist>
+	    <listitem><para>allow to specify a name (and optionally a description)</para></listitem>
+	    <listitem><para>allow to specify a type, see <link linkend="gda-g-type-from-string">gda_g_type_from_string()</link></para></listitem>
+	    <listitem><para>allow to specify if the variable can be NULL</para></listitem>
+	  </itemizedlist>
+	</para>
+	<para>For more information, refer to the <link linkend="GdaSqlParser.description">GdaSqlParser object's documentation</link></para>
+      </sect1>
+
+      <sect1 id="null_handling">
+	<title>NULL handling when using variables</title>
+	<para>
+	  When using variables in statements (see <link linkend="placeholders">Variables syntax in SQL</link>)
+	  for example like <programlisting>SELECT * FROM users WHERE name = ##name::string::null;</programlisting>,
+	  database engines will generally not handle correctly the case where a variable is valued to NULL. For instance
+	  this example would result in the code being executed as <programlisting>SELECT * FROM users WHERE name = NULL;</programlisting> which would probably give no result, whereas the expected equivalent code would be
+	  <programlisting>SELECT * FROM users WHERE name IS NULL;</programlisting>
+	</para>
+	<para>
+	   &LIBGDA; automatically handles theses cases and makes sure the <code>IS NULL</code> or <code>IS NOT NULL</code>
+	   constructions are used when necessary. It won't of course handle variable's NULL values when using other
+	   operators that equal or different, tough.
+	</para>
+      </sect1>
+
+      <sect1 id="gen:sql_identifiers">
+	<title>SQL identifiers</title>
+	<para>
+	  The SQL standard has never defined if SQL identifiers (database object's names) have to be case sensitive
+	  or not, leaving that
+	  subject to each database engine implementation. All of them accept two syntaxes for SQL identifiers:
+	  <itemizedlist>
+	    <listitem><para>the first is if the SQL identifier is surrounded by double quotes (sometimes backquotes
+		or other characters), usually making the SQL identifier case sensitive (and also making
+		it possible to use reserved SQL keywords as identifiers).</para></listitem>
+	    <listitem><para>the second is if it's not enquoted, usually meaning that the SQL identifier is not
+		case sensitive.</para></listitem>
+	  </itemizedlist>
+	  <note>
+	    <para>Sometimes those rules don't apply or apply only partially. For example a MySQL server, depending
+	      on how it is configured and on what kind of OS it is running on, will have different sets of meanings
+	      for these notations.
+	    </para>
+	  </note>
+	</para>
+
+	<para>
+	  As a result, &LIBGDA; has to be the least intrusive possible when the user wants to execute an SQL statement,
+	  and lets the database being accessed apply its own rules. However &LIBGDA; features meta data information
+	  retrieval (getting the list of tables, views,...) and there some representation conventions have been fixed,
+	  see the <link linkend="information_schema:sql_identifiers">meta data section about SQL identifiers</link>
+	  for more information.
+	</para>
+
+	<para>
+	  The following diagram illustrates how &LIBGDA; handles SQL identifiers' representations depending where
+	  they are used:
+	  <mediaobject>
+	    <imageobject role="html">
+	      <imagedata fileref="SqlIdentifiers.png" format="PNG"/>
+	    </imageobject>
+	    <textobject>
+	      <phrase>Diagram illustrating how &LIBGDA; handles SQL identifiers' representations</phrase>
+	    </textobject>
+	  </mediaobject>
+	</para>
+      </sect1>
+
+      <sect1 id="gen_blobs">
+	<title>Binary large objects (BLOBs)</title>
+	<para>
+	  Binary large objects (BLOBs) are potentially very big (several 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 to the database engine at the same time
+	  as the SQL text is transfered: first
+	  a reference to a blob is created for an existing or a new blob, and then
+	  that reference is used, <emphasis>before or after the statement is being executed,
+	    depending on the database engine accessed</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>
+	<para>
+	  Please consult each database provider's <link linkend="provider-notes">notes</link> and
+	  <link linkend="limitations">limitations</link> for database specific rules
+	  regarding BLOBs. Also have a look at the
+	  <link linkend="blobs_example">Blobs manipulation source code example</link>.
+	</para>
+      </sect1>
+
+    </chapter>
\ No newline at end of file
diff --git a/doc/C/libgda-4.0-docs.sgml b/doc/C/libgda-4.0-docs.sgml
index 36a9011..b21f4ce 100644
--- a/doc/C/libgda-4.0-docs.sgml
+++ b/doc/C/libgda-4.0-docs.sgml
@@ -37,6 +37,7 @@
 <!ENTITY gda-test-connection "<command>gda-test-connection-4.0</command>">
 <!ENTITY fullexample SYSTEM "examples/full_example.c">
 <!ENTITY blobsexample SYSTEM "examples/blobtest.c">
+<!ENTITY abstraction SYSTEM "abstraction.xml">
 <!ENTITY install SYSTEM "installation.xml">
 <!ENTITY examples SYSTEM "gettingstarted.xml">
 <!ENTITY migration SYSTEM "migration.xml">
@@ -443,6 +444,7 @@
       </mediaobject>
     </chapter>
 
+    &abstraction;
     &install;
     &examples;
     &migration;
@@ -455,93 +457,6 @@
     <para>
       The following sections describe the API available for &GDA; applications.
     </para>
-    <chapter>
-      <title>Foreword about abstraction</title>
-      <para>
-	&LIBGDA; aims both at making it easier to use databases and, for applications written using it, 
-	at making it easier to switch to a different database or to to be able to use different types of databases
-	with a minimum or no code modifications. To achieve the 2nd goal, &LIBGDA; proposes an abstraction of
-	most of database's engine features, which has to be understood to write portable code.
-      </para>
-
-      <sect1 id="gen:sql_identifiers">
-	<title>SQL identifiers</title>
-	<para>
-	  The SQL standard has never defined if SQL identifiers (database object's names) have to be case sensitive
-	  or not, leaving that
-	  subject to each database engine implementation. All of them accept two syntaxes for SQL identifiers:
-	  <itemizedlist>
-	    <listitem><para>the first is if the SQL identifier is surrounded by double quotes (sometimes backquotes
-		or other characters), usually making the SQL identifier case sensitive (and also making
-		it possible to use reserved SQL keywords as identifiers).</para></listitem>
-	    <listitem><para>the second is if it's not enquoted, usually meaning that the SQL identifier is not
-		case sensitive.</para></listitem>
-	  </itemizedlist>
-	  <note>
-	    <para>Sometimes those rules don't apply or apply only partially. For example a MySQL server, depending
-	      on how it is configured and on what kind of OS it is running on, will have different sets of meanings
-	      for these notations.
-	    </para>
-	  </note>
-	</para>
-
-	<para>
-	  As a result, &LIBGDA; has to be the least intrusive possible when the user wants to execute an SQL statement,
-	  and lets the database being accessed apply its own rules. However &LIBGDA; features meta data information
-	  retrieval (getting the list of tables, views,...) and there some representation conventions have been fixed,
-	  see the <link linkend="information_schema:sql_identifiers">meta data section about SQL identifiers</link>
-	  for more information.
-	</para>
-
-	<para>
-	  The following diagram illustrates how &LIBGDA; handles SQL identifiers' representations depending where
-	  they are used:
-	  <mediaobject>
-	    <imageobject role="html">
-	      <imagedata fileref="SqlIdentifiers.png" format="PNG"/>
-	    </imageobject>
-	    <textobject>
-	      <phrase>Diagram illustrating how &LIBGDA; handles SQL identifiers' representations</phrase>
-	    </textobject>
-	  </mediaobject>
-	</para>
-      </sect1>
-
-      <sect1 id="gen_blobs">
-	<title>Binary large objects (BLOBs)</title>
-	<para>
-	  Binary large objects (BLOBs) are potentially very big (several 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 to the database engine at the same time
-	  as the SQL text is transfered: first
-	  a reference to a blob is created for an existing or a new blob, and then
-	  that reference is used, <emphasis>before or after the statement is being executed,
-	    depending on the database engine accessed</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>
-	<para>
-	  Please consult each database provider's <link linkend="provider-notes">notes</link> and
-	  <link linkend="limitations">limitations</link> for database specific rules
-	  regarding BLOBs. Also have a look at the
-	  <link linkend="blobs_example">Blobs manipulation source code example</link>.
-	</para>
-      </sect1>
-
-    </chapter>
 
     &howto;
     <chapter>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]