[libgda] Improved documentation bits
- From: Vivien Malerba <vivien src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libgda] Improved documentation bits
- Date: Thu, 20 Jan 2011 18:39:32 +0000 (UTC)
commit a38d4b5ab4885baee1a11e2eaaf9eda4051651f4
Author: Vivien Malerba <malerba gnome-db org>
Date: Thu Jan 20 19:37:36 2011 +0100
Improved documentation bits
doc/C/gda-sql-manual.xml | 8 ++-
doc/C/howto.xml | 118 +++++++++++++++++++++++--------------
doc/C/installation.xml | 147 ++++++++++++++++++++-------------------------
3 files changed, 143 insertions(+), 130 deletions(-)
---
diff --git a/doc/C/gda-sql-manual.xml b/doc/C/gda-sql-manual.xml
index 9048b70..df81fe8 100644
--- a/doc/C/gda-sql-manual.xml
+++ b/doc/C/gda-sql-manual.xml
@@ -344,9 +344,11 @@ cnc3>
to list a table's attributes, or for command line completion.
</para>
<para>
- If some modifications to the database structure have been made (either from the SQL console or from another tool), then
- the meta data must be updated using the <command>.meta</command> command, which does not output anything unless an error
- occurred.
+ If some modifications to the database structure have been made using a tool not using &LIBGDA;, then
+ the meta data must be updated using the <command>.meta</command> command, which does not output
+ anything unless an error occurred. Updates to the meta data are automatic when a shema change
+ is done using &LIBGDA; if the connection has been opened using the GDA_CONNECTION_OPTIONS_AUTO_META_DATA flag
+ (which is the case for &LIBGDA;'s own tools).
</para>
<para>
As the meta data are also stored in a database, the console tool allows one to directly execute SQL commands in the
diff --git a/doc/C/howto.xml b/doc/C/howto.xml
index 69ad5a7..31b35aa 100644
--- a/doc/C/howto.xml
+++ b/doc/C/howto.xml
@@ -105,8 +105,8 @@ gda_sql_builder_select_add_field (b, "lastname", "people", NULL);
gda_sql_builder_select_add_field (b, "date", NULL, "birthdate");
gda_sql_builder_select_add_field (b, "age", NULL, NULL);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "people"),
- NULL);
+ gda_sql_builder_add_id (b, "people"),
+ NULL);
[...]
g_object_unref (b);
</programlisting>
@@ -118,18 +118,19 @@ g_object_unref (b);
<programlisting>
GdaSqlBuilder *b;
b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
-guint id_table = gda_sql_builder_add_id (b, "select"); /* SELECT is an SQL reserved keyword */
-guint id_target1 = gda_sql_builder_select_add_target_id (b, id_table, "c");
-guint id_target2 = gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "orders"),
- NULL);
-guint id_join = gda_sql_builder_select_join_targets (b, id_target1, id_target2, GDA_SQL_SELECT_JOIN_INNER, 0);
+GdaSqlBuilderId id_table = gda_sql_builder_add_id (b, "select"); /* SELECT is an SQL reserved keyword */
+GdaSqlBuilderId id_target1 = gda_sql_builder_select_add_target_id (b, id_table, "c");
+GdaSqlBuilderId id_target2 = gda_sql_builder_select_add_target_id (b,
+ gda_sql_builder_add_id (b, "orders"),
+ NULL);
+GdaSqlBuilderId id_join = gda_sql_builder_select_join_targets (b, id_target1, id_target2, GDA_SQL_SELECT_JOIN_INNER, 0);
+/* DATE is an SQL reserved keyword */
gda_sql_builder_add_field_value_id (b,
- gda_sql_builder_add_id (b, "c.date"), 0); /* DATE is an SQL reserved keyword */
+ gda_sql_builder_add_id (b, "c.date"), 0);
gda_sql_builder_add_field_value_id (b,
- gda_sql_builder_add_id (b, "name"),
- gda_sql_builder_add_id (b, "person"));
+ gda_sql_builder_add_id (b, "name"),
+ gda_sql_builder_add_id (b, "person"));
gda_sql_builder_join_add_field (b, id_join, "id");
[...]
@@ -145,9 +146,9 @@ GdaSqlBuilder *b;
b = gda_sql_builder_new (GDA_SQL_STATEMENT_INSERT);
gda_sql_builder_set_table (b, "products");
gda_sql_builder_add_field_value (b, "ref", G_TYPE_STRING, "A0E'FESP");
-guint id_field = gda_sql_builder_add_id (b, "id");
-guint id_value = gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 14);
-guint id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_value, 0);
+GdaSqlBuilderId id_field = gda_sql_builder_add_id (b, "id");
+GdaSqlBuilderId id_value = gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 14);
+GdaSqlBuilderId id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_value, 0);
gda_sql_builder_set_where (b, id_cond);
[...]
g_object_unref (b);
@@ -161,9 +162,9 @@ g_object_unref (b);
GdaSqlBuilder *b;
b = gda_sql_builder_new (GDA_SQL_STATEMENT_DELETE);
gda_sql_builder_set_table (b, "items");
-guint id_field = gda_sql_builder_add_id (b, "id");
-guint id_param = gda_sql_builder_add_param (b, "theid", G_TYPE_INT, FALSE);
-guint id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_param, 0);
+GdaSqlBuilderId id_field = gda_sql_builder_add_id (b, "id");
+GdaSqlBuilderId id_param = gda_sql_builder_add_param (b, "theid", G_TYPE_INT, FALSE);
+GdaSqlBuilderId id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_param, 0);
gda_sql_builder_set_where (b, id_cond);
[...]
g_object_unref (b);
@@ -179,11 +180,11 @@ b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
gda_sql_builder_select_add_target_id (b,
gda_sql_builder_add_id (b, "mytable"),
NULL);
-guint id_function = gda_sql_builder_add_function (b, "myfunc",
- gda_sql_builder_add_id (b, "a"),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 5),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Joe"),
- 0);
+GdaSqlBuilderId id_function = gda_sql_builder_add_function (b, "myfunc",
+ gda_sql_builder_add_id (b, "a"),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 5),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Joe"),
+ 0);
gda_sql_builder_add_field_value_id (b, id_function, 0);
[...]
g_object_unref (b);
@@ -199,19 +200,19 @@ GdaSqlStatement *sub;
b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "id"), 0);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "subdata"),
- NULL);
+ gda_sql_builder_add_id (b, "subdata"),
+ NULL);
sub = gda_sql_builder_get_sql_statement (b, FALSE);
g_object_unref (b);
b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "name"), 0);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "master"),
- NULL);
-guint id_field = gda_sql_builder_add_id (b, "id");
-guint id_subselect = gda_sql_builder_add_sub_select (b, sub, TRUE);
-guint id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_IN, id_field, id_subselect, 0);
+ gda_sql_builder_add_id (b, "master"),
+ NULL);
+GdaSqlBuilderId id_field = gda_sql_builder_add_id (b, "id");
+GdaSqlBuilderId id_subselect = gda_sql_builder_add_sub_select (b, sub, TRUE);
+GdaSqlBuilderId id_cond = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_IN, id_field, id_subselect, 0);
gda_sql_builder_set_where (b, id_cond);
[...]
g_object_unref (b);
@@ -229,8 +230,8 @@ gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "id"), 0);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "name"), 0);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "location"), 0);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "subdate"),
- NULL);
+ gda_sql_builder_add_id (b, "subdate"),
+ NULL);
sub = gda_sql_builder_get_sql_statement (b, FALSE);
g_object_unref (b);
@@ -255,8 +256,8 @@ b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "id"), 0);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "name"), 0);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "subdata1"),
- NULL);
+ gda_sql_builder_add_id (b, "subdata1"),
+ NULL);
sub1 = gda_sql_builder_get_sql_statement (b, FALSE);
g_object_unref (b);
@@ -264,8 +265,8 @@ b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "ident"), 0);
gda_sql_builder_add_field_value_id (b, gda_sql_builder_add_id (b, "lastname"), 0);
gda_sql_builder_select_add_target_id (b,
- gda_sql_builder_add_id (b, "subdata2"),
- NULL);
+ gda_sql_builder_add_id (b, "subdata2"),
+ NULL);
sub2 = gda_sql_builder_get_sql_statement (b, FALSE);
g_object_unref (b);
@@ -283,16 +284,16 @@ g_object_unref (b);
<programlisting>
GdaSqlBuilder *b;
b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
-guint id_case = gda_sql_builder_add_case (b,
- gda_sql_builder_add_id (b, "tag"),
- 0,
- gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Alpha"),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 1),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Bravo"),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 2),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Charlie"),
- gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 3),
- 0);
+GdaSqlBuilderId id_case = gda_sql_builder_add_case (b,
+ gda_sql_builder_add_id (b, "tag"),
+ 0,
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Alpha"),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 1),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Bravo"),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 2),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "Charlie"),
+ gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 3),
+ 0);
gda_sql_builder_add_field_value_id (b, id_case, 0);
gda_sql_builder_select_add_target_id (b,
gda_sql_builder_add_id (b, "data"),
@@ -302,6 +303,33 @@ g_object_unref (b);
</programlisting>
</para>
</sect2>
+
+ <sect2>
+ <title>SELECT product_id, name, sum (4 * 5 * price * 1.200000) FROM invoice_lines</title>
+ <para>
+ <programlisting>
+GdaSqlBuilder *b;
+b = gda_sql_builder_new (GDA_SQL_STATEMENT_SELECT);
+gda_sql_builder_select_add_field (b, "product_id", NULL, NULL);
+gda_sql_builder_select_add_field (b, "name", NULL, NULL);
+
+GdaSqlBuilderId op_ids[4], id_function;
+op_ids[0] = gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 4);
+op_ids[1] = gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 5);
+op_ids[2] = gda_sql_builder_add_id (b, "price");
+op_ids[3] = gda_sql_builder_add_expr (b, NULL, G_TYPE_FLOAT, 1.2);
+id_function = gda_sql_builder_add_function (b, "sum",
+ gda_sql_builder_add_cond_v (b, GDA_SQL_OPERATOR_TYPE_STAR, op_ids, 4),
+ 0);
+gda_sql_builder_add_field_value_id (b, id_function, 0);
+gda_sql_builder_select_add_target_id (b,
+ gda_sql_builder_add_id (b, "invoice_lines"),
+ NULL);
+[...]
+g_object_unref (b);
+ </programlisting>
+ </para>
+ </sect2>
</sect1>
<sect1 id="howto-exec-select">
diff --git a/doc/C/installation.xml b/doc/C/installation.xml
index dc7bb5d..2c2d4ab 100644
--- a/doc/C/installation.xml
+++ b/doc/C/installation.xml
@@ -20,27 +20,33 @@
compile the software. To do so, once you have unpacked
the source tree, you must:
<programlisting>
-<prompt>$</prompt>/configure
-<prompt>$</prompt>make
-<prompt>$</prompt>make install
+<prompt>$ </prompt>./configure
+<prompt>$ </prompt>make
+<prompt>$ </prompt>make install
</programlisting>
</para>
<para>
This will generate the makefiles for your specific platform,
compile all the source tree, and install the binaries and
- documentation in your system.
+ documentation in your system. This method works in the following environments:
+ <itemizedlist mark="bullet">
+ <listitem><para>On Linux (or other Unix systems, including MacOSX)</para></listitem>
+ <listitem><para>On linux using the MinGW compiler in a cross compilation environment to generate Windows binaries</para></listitem>
+ <listitem><para>On Windows using the MinGW compiler</para></listitem>
+ </itemizedlist>
</para>
<para>
- If you don't find a file named <filename>configure</filename>, there
- should be one called <filename>autogen.sh</filename>. In this case,
- run <filename>autogen.sh</filename>, which will create and run the
- generated <filename>configure</filename> file.
+ If you don't find a file named <filename>configure</filename>, usually because you use
+ non packaged sources which come from a Git repository, then
+ execute the <filename>autogen.sh</filename> script which will create and run the
+ generated <filename>configure</filename> file (please not that for this script to work,
+ you'll need to have the autotools components installed on your system).
</para>
<para>
You can specify several arguments to <filename>configure</filename> (or
- <filename>autogen.sh</filename>). The most significant are (you can
+ <filename>autogen.sh</filename>). You can
check all the available arguments by running
- <command>configure --help</command>):
+ <command>configure --help</command>, but the most significant ones are:
</para>
<itemizedlist mark="bullet">
<listitem>
@@ -57,51 +63,30 @@
</listitem>
<listitem>
<para>
- <userinput>--enable-debug</userinput>: Specify to explicietly print some debuging
- information
+ <userinput>--enable-warnings</userinput>: Specify compilation warnings, to choose from:
+ min, max, fatal or no.
</para>
</listitem>
<listitem>
<para>
- <userinput>--with-mysql=<directory></userinput>: Specify
- directory where &MYSQL; libraries are installed
+ <userinput>--with-<provider name>=[yes/no/<directory>]</userinput>: Specify, for
+ each supported database type (bdb, mysql, postgres, oracle, java, mdb) if the corresponding
+ provider is resquired ("yes"), should not be built ("no"), or can be built if its development
+ files can be detected by the configure script (you can specify a directory to look into if these
+ files are installed in a non standard location, for example
+ <userinput>--with-oracle=/local/BASES/OCI32</userinput>).
</para>
</listitem>
<listitem>
<para>
- <userinput>--with-postgres=<directory></userinput>:
- Specify directory where &PGSQL; libraries are installed
+ <userinput>--enable-system-sqlite</userinput>: Specify that the SQLite installed with the
+ system must be used instead of the embedded version.
</para>
</listitem>
<listitem>
<para>
- <userinput>--with-sybase=<directory></userinput>: Specify
- directory where &SYBASE; libraries are installed
- </para>
- </listitem>
- <listitem>
- <para>
- <userinput>--with-ldap=<directory></userinput>: Specify
- directory where &LDAP; libraries are installed
- </para>
- </listitem>
- <listitem>
- <para>
- <userinput>--with-oracle=<directory></userinput>: Specify
- directory where &ORAC; libraries are installed
- </para>
- </listitem>
- <listitem>
- <para>
- <userinput>--with-interbase=<directory></userinput>: Specify
- directory where &INTERB; libraries are installed
- </para>
- </listitem>
- <listitem>
- <para>
- <userinput>--with-mdb=<directory></userinput>: Specify
- directory where the MDB libraries (for accessing &MSACC; files)
- are installed
+ <userinput>--with-ui</userinput>: Require that the UI extension (using GTK+) be built. This
+ also enables building the graphical tools such as the control center and GdaBrowser.
</para>
</listitem>
</itemizedlist>
@@ -122,16 +107,22 @@
</para>
</sect1>
<sect1 id="compiling">
- <title>Compiling with the library</title>
+ <title>Compiling your code using the &LIBGDA; library</title>
<para>
To compile you will need to set the C flags and to link the library, so we recommend
to use the <command>pkg-config</command> command.
</para>
<programlisting>
-<systemitem class="prompt">$</systemitem>gcc -c full_example.c `pkg-config --cflags libgda-4.0`
-<systemitem class="prompt">$</systemitem>gcc -o full_example `pkg-config --libs libgda-4.0` full_example.o
+<systemitem class="prompt">$ </systemitem>gcc -c full_example.c `pkg-config --cflags libgda-4.0`
+<systemitem class="prompt">$ </systemitem>gcc -o full_example `pkg-config --libs libgda-4.0` full_example.o
</programlisting>
<para>
+ or more simply:
+ <programlisting>
+<systemitem class="prompt">$ </systemitem>gcc -o full_example `pkg-config --cflags --libs libgda-4.0` full_example.c
+ </programlisting>
+ </para>
+ <para>
Doing this will add to the C compiler command line all needed header files
and library directories as well as all needed libraries for linking your GDA
application. To include header files, you can use <filename>libgda/libgda.h</filename>
@@ -149,8 +140,7 @@
<title>Configuration for development</title>
<para>
If you want to develop applications using &LIBGDA;, you should
- install the libgda-dev[el] package if you do a &RPM; or <link
- linkend="installation-debian">Debian-based</link>
+ install the libgda-dev[el] package if you do a &RPM; or <link linkend="installation-debian">Debian-based</link>
installation. If you compiled the source code, development files are
installed in your system.
</para>
@@ -213,8 +203,8 @@
(which
is created the first time &LIBGDA; is used within an application. System wide DSN are defined in the
<filename><prefix>/etc/libgda/config</filename>. Rather than editing that
- file manually, it is possible to use the <command>gnome-database-properties-4.0</command>
- from the <ulink url="http://www.gnome-db.org";>Libgnomedb</ulink> library.
+ file manually, it is possible to use the <command>gda-control-center-4.0</command> tool
+ (part of &LIBGDA;).
Note: if the <filename>$HOME/.libgda/config</filename> already exists from a previous use
of &LIBGDA;, then that file is used instead of
<filename>$HOME/.local/share/libgda/config</filename>.
@@ -228,9 +218,9 @@
&LIBGDA; providers.
</para>
<sect3 id="installation-provider-default">
- <title>Default provider</title>
+ <title>SQLite provider</title>
<para>
- The &GDA; default provider (based on an SQLite database file) is always installed
+ The SQLite provider is always installed (it is required by &LIBGDA;'s internally)
with &LIBGDA;, which means that a default database system is always available.
Specifically the first time you use
&LIBGDA;, a test database is copied into <filename>$HOME/.local/share/libgda/config</filename>
@@ -239,40 +229,33 @@
named "SalesTest".
</para>
</sect3>
- <sect3 id="installation-provider-odbc">
- <title>&ODBC; Provider</title>
- <para>
- The &ODBC; provider is a special case, since &ODBC; is itself a
- data access layer, the same as &LIBGDA;. So, in the case of the
- &GDA; &ODBC; provider, the &DSN; string is completely up to the
- &ODBC; driver manager. That is, the &GDA; &ODBC; provider does not
- parse it all, nor does it try to understand what it means; it
- simply passes it over to the &ODBC; library.
- </para>
- <para>
- So, if you want to use &LIBGDA; with &ODBC;, you should first know
- how to set up an &ODBC; data source, and then just specify the
- &DSN; string you would pass to the &ODBC; library in the &DSN;
- string of the &GDA; data sources.
- </para>
- <para>
- There is a project called
- <ulink url="http://www.unixodbc.org";>unixODBC</ulink>,
- which provides some graphical tools to help you in
- setting up &ODBC; data sources. You may find it
- interesting to give it a try.
- </para>
- </sect3>
<sect3 id="installation-provider-all">
- <title>Common to all provider</title>
+ <title>Connection information for each database provider</title>
<para>
Each provider exports a list of the arguments it requires in
its connection string which is used internally by &LIBGDA; to
- establish each connection. If you don't use a GUI which proposes
- you valid choices (such as &GNOMEDB;), you can get that list in
- each file named <filename><provider_name>_specs_dsn.xml</filename>
- installed in the <filename>$PREFIX/share/libgda</filename> directory.
- This file is easy to parse and read.
+ establish each connection. To obtain the required information to open a connection
+ using a provider, use the <link linkend="gda-sql">Gda SQL console tool</link> with the
+ <userinput>-L <provider name></userinput> option. For example for PostgreSQL (strings truncated
+ for better readability):
+ <programlisting>
+<systemitem class="prompt">$ </systemitem>gda-sql -L PostgreSQL
+ Provider 'PostgreSQL' description
+Attribute | Value
+---------------+-------------------------------------------------------------
+Provider | PostgreSQL
+Description | Provider for PostgreSQL databases
+DSN parameters | DB_NAME: The name of a database to connect to (string),
+ SEARCHPATH: Search path among database's schemas ('search_pa
+ HOST: Host on which the database server is running (for serv
+ PORT: Database server port (for servers running on unix doma
+ OPTIONS: Extra connection options (string),
+ USE_SSL: Whether or not to use SSL to establish the connecti
+Authentication | USERNAME (string),
+ PASSWORD (string)
+File | /local/lib/libgda-4.0/providers/libgda-postgres.so
+(5 rows)
+ </programlisting>
</para>
</sect3>
</sect2>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
