[libgda] Doc. improvements
- From: Vivien Malerba <vivien src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libgda] Doc. improvements
- Date: Tue, 30 Aug 2011 19:06:21 +0000 (UTC)
commit 7dbb6c2f5fa47857b16757c9c54f2b0845165ff1
Author: Vivien Malerba <malerba gnome-db org>
Date: Tue Aug 30 21:05:21 2011 +0200
Doc. improvements
doc/C/Makefile.am | 2 +-
doc/C/abstraction.xml | 124 ++++++++++++++++++++++++++++++++++++++++++++
doc/C/libgda-5.0-docs.sgml | 89 +-------------------------------
3 files changed, 127 insertions(+), 88 deletions(-)
---
diff --git a/doc/C/Makefile.am b/doc/C/Makefile.am
index ac80cd1..dc03a46 100644
--- a/doc/C/Makefile.am
+++ b/doc/C/Makefile.am
@@ -79,7 +79,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-virtual-methods.xml prov-writing-recordsets.xml prov-writing-blobs.xml prov-writing-parser.xml prov-writing-assembly.xml \
packaging.xml packaging_ui.xml i_s_doc.xml howto.xml gda-sql-manual.xml data_validation.xml data_select.xml \
DataModels.svg \
diff --git a/doc/C/abstraction.xml b/doc/C/abstraction.xml
new file mode 100644
index 0000000..f69896e
--- /dev/null
+++ b/doc/C/abstraction.xml
@@ -0,0 +1,124 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";[
+<!ENTITY LIBGDA "<application>Libgda</application>">
+]>
+ <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>$<number></code>, <code>:<name></code>, <code>?<number></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-5.0-docs.sgml b/doc/C/libgda-5.0-docs.sgml
index fb1904a..3134cdb 100644
--- a/doc/C/libgda-5.0-docs.sgml
+++ b/doc/C/libgda-5.0-docs.sgml
@@ -304,6 +304,8 @@
</mediaobject>
</chapter>
+ <xi:include href="abstraction.xml"/>
+
<xi:include href="installation.xml"/>
<xi:include href="gettingstarted.xml"/>
<xi:include href="migration.xml"/>
@@ -317,93 +319,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>
<xi:include href="howto.xml"/>
<chapter>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
