GNOME.org
 

libgda r3348 - in trunk: . doc/C doc/C/tmpl libgda

Author: vivien
Date: Tue Mar 10 21:36:05 2009
New Revision: 3348
URL: http://svn.gnome.org/viewvc/libgda?rev=3348&view=rev

Log:
2009-03-10  Vivien Malerba <malerba gnome-db org>

	* libgda/gda-statement.c:
	* doc/C:
	  - documents gda_statement_to_sql_real(), fixes bug #574738
	  - mention that GdaServerOperationNode is mainly for database provider's
	    implementations, for bug #574742
	* libgda/gda-meta-struct.c: fixes documentation for
	gda_meta_struct_get_all_db_objects(), fixes bug #574740


Added:
   trunk/doc/C/tmpl/provider-support-sql.sgml
Modified:
   trunk/ChangeLog
   trunk/doc/C/libgda-4.0-docs.sgml
   trunk/doc/C/libgda-4.0-sections.txt
   trunk/doc/C/tmpl/gda-server-operation-nodes.sgml
   trunk/doc/C/tmpl/gda-statement.sgml
   trunk/libgda/gda-meta-struct.c
   trunk/libgda/gda-statement.c

Modified: trunk/doc/C/libgda-4.0-docs.sgml
==============================================================================
--- trunk/doc/C/libgda-4.0-docs.sgml	(original)
+++ trunk/doc/C/libgda-4.0-docs.sgml	Tue Mar 10 21:36:05 2009
@@ -107,6 +107,7 @@
 <!ENTITY libgda-GdaDataComparator SYSTEM "xml/gda-data-comparator.xml">
 <!ENTITY provider-writing SYSTEM "prov-writing.xml">
 <!ENTITY provider-support SYSTEM "xml/provider-support.xml">
+<!ENTITY provider-support-sql SYSTEM "xml/provider-support-sql.xml">
 <!ENTITY i-s-doc SYSTEM "i_s_doc.xml">
 <!ENTITY fdl-appendix SYSTEM "fdl-appendix.sgml">
 <!ENTITY howto SYSTEM "howto.xml">
@@ -1363,6 +1364,7 @@
       &libgda-GdaDataSelectPriv;
       &libgda-PStmt;
       &libgda-quark-list;
+      &provider-support-sql;
       &provider-support;
     </chapter>
     &provider-writing;

Modified: trunk/doc/C/libgda-4.0-sections.txt
==============================================================================
--- trunk/doc/C/libgda-4.0-sections.txt	(original)
+++ trunk/doc/C/libgda-4.0-sections.txt	Tue Mar 10 21:36:05 2009
@@ -1461,6 +1461,18 @@
 </SECTION>
 
 <SECTION>
+<FILE>provider-support-sql</FILE>
+<TITLE>SQL rendering API</TITLE>
+<INCLUDE>libgda/gda-statement-extra.h</INCLUDE>
+GdaSqlRenderingContext
+GdaSqlRenderingValue
+GdaSqlRenderingPSpecFunc
+GdaSqlRenderingExpr
+GdaSqlRenderingFunc
+gda_statement_to_sql_real
+</SECTION>
+
+<SECTION>
 <FILE>gda-data-comparator</FILE>
 <TITLE>GdaDataComparator</TITLE>
 GdaDataComparator

Modified: trunk/doc/C/tmpl/gda-server-operation-nodes.sgml
==============================================================================
--- trunk/doc/C/tmpl/gda-server-operation-nodes.sgml	(original)
+++ trunk/doc/C/tmpl/gda-server-operation-nodes.sgml	Tue Mar 10 21:36:05 2009
@@ -12,9 +12,10 @@
   gda_server_operation_set_value_at()'s documentation.
 </para>
 <para>
-  This API is designed to get information about all the nodes present in a #GdaServerOperation object (the
+  This API is designed to get information about all the nodes present in a #GdaServerOperation object (refer to the
   gda_server_operation_get_root_nodes() function) and about each node of a path, and allows inspection
-  of its contents.
+  of its contents. It is mainly reserved for database provider's implementations but can have its purpose
+  outside of this scope.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

Modified: trunk/doc/C/tmpl/gda-statement.sgml
==============================================================================
--- trunk/doc/C/tmpl/gda-statement.sgml	(original)
+++ trunk/doc/C/tmpl/gda-statement.sgml	Tue Mar 10 21:36:05 2009
@@ -61,18 +61,16 @@
 
 <!-- ##### ENUM GdaStatementSqlFlag ##### -->
 <para>
-These flags control how a #GdaStatement will be rendered as SQL. If no "GDA_STATEMENT_SQL_PARAMS..." flag is specified, then
-for each parameter (variable) required by the statement, there must be a value provided when converting to SQL (through
-the @params argument of the gda_statement_to_sql_extended() function), or an error will be reported.
+  Specifies how the general rendering is done
 </para>
 
- GDA_STATEMENT_SQL_PRETTY: indents the output for easier readability
- GDA_STATEMENT_SQL_PARAMS_LONG: use the &lt;default value&gt; /* ... */ syntax for each parameter
- GDA_STATEMENT_SQL_PARAMS_SHORT: use the ##&lt;param_name&gt; syntax for each parameter when possible
- GDA_STATEMENT_SQL_PARAMS_AS_COLON: use the :&lt;param_name&gt; syntax for each parameter, replacing any char not in [0-9A-Za-z] by '_'
- GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR: use the $&lt;param_number&gt; syntax for each parameter (starting numbering at 1)
- GDA_STATEMENT_SQL_PARAMS_AS_QMARK: use the ?&lt;param_number&gt; syntax for each parameter (starting numbering at 1)
- GDA_STATEMENT_SQL_PARAMS_AS_UQMARK: use the ? syntax for each parameter (no numbering)
+ GDA_STATEMENT_SQL_PRETTY: rendering will include newlines and indentation to make it easy to read
+ GDA_STATEMENT_SQL_PARAMS_LONG: parameters will be rendered using the "/* name:&lt;param_name&gt; ... */" syntax
+ GDA_STATEMENT_SQL_PARAMS_SHORT: parameters will be rendered using the "##&lt;param_name&gt;..." syntax
+ GDA_STATEMENT_SQL_PARAMS_AS_COLON: parameters will be rendered using the ":&lt;param_name&gt;" syntax
+ GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR: parameters will be rendered using the "$&lt;param_number&gt;" syntax where parameters are numbered starting from 1
+ GDA_STATEMENT_SQL_PARAMS_AS_QMARK: parameters will be rendered using the "?&lt;param_number&gt;" syntax where parameters are numbered starting from 1
+ GDA_STATEMENT_SQL_PARAMS_AS_UQMARK: parameters will be rendered using the "?" syntax
 
 <!-- ##### ENUM GdaStatementModelUsage ##### -->
 <para>

Added: trunk/doc/C/tmpl/provider-support-sql.sgml
==============================================================================
--- (empty file)
+++ trunk/doc/C/tmpl/provider-support-sql.sgml	Tue Mar 10 21:36:05 2009
@@ -0,0 +1,130 @@
+<!-- ##### SECTION Title ##### -->
+SQL rendering API
+
+<!-- ##### SECTION Short_Description ##### -->
+Adapting the SQL to the database's own SQL dialect
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+  &LIBGDA; is able to render a #GdaStatement statement to SQL in a generic way (as close as possible to the SQL
+  standard). However as each database has ultimately its own SQL dialect, some parts of the rendering has
+  to be specialized.
+</para>
+<para>
+  Customization is achieved by providing custom implementations of SQL rendering functions for each kind of
+  part in a #GdaSqlStatement structure, all packed in a #GdaSqlRenderingContext context structure. Functions
+  which are not customized will be implemented by the default ones.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+  <link linkend="gda-statement-to-sql-extended">gda_statement_to_sql_extended()</link>
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT GdaSqlRenderingContext ##### -->
+<para>
+  Structure to wrap all the individual part's SQL rendering functions
+</para>
+
+ flags: Global rendering options
+ params: Parameters to be used while doing the rendering
+ params_used: When rendering is complete, contains the ordered list of parameters which have been used while doing the rendering
+ provider: Pointer to the server provider to be used
+ cnc: Pointer to the connection to be used
+ render_value: function to render a #GValue
+ render_param_spec: function to render a #GdaSqlParamSpec
+ render_expr: function to render a #GdaSqlExpr
+ render_unknown: function to render a #GdaSqlStatementUnknown
+ render_begin: function to render a BEGIN #GdaSqlStatementTransaction
+ render_rollback: function to render a ROLLBACK #GdaSqlStatementTransaction
+ render_commit: function to render a COMMIT #GdaSqlStatementTransaction
+ render_savepoint: function to render a ADD SAVEPOINT #GdaSqlStatementTransaction
+ render_rollback_savepoint: function to render a ROLBACK SAVEPOINT #GdaSqlStatementTransaction
+ render_delete_savepoint: function to render a DELETE SAVEPOINT #GdaSqlStatementTransaction
+ render_select: function to render a #GdaSqlStatementSelect
+ render_insert: function to render a #GdaSqlStatementInsert
+ render_delete: function to render a #GdaSqlStatementDelete
+ render_update: function to render a #GdaSqlStatementUpdate
+ render_compound: function to render a #GdaSqlStatementCompound
+ render_field: function to render a #GdaSqlField
+ render_table: function to render a #GdaSqlTable
+ render_function: function to render a #GdaSqlFunction
+ render_operation: function to render a #GdaSqlOperation
+ render_case: function to render a #GdaSqlCase
+ render_select_field: function to render a #GdaSqlSelectField
+ render_select_target: function to render a #GdaSqlSelectTarget
+ render_select_join: function to render a #GdaSqlSelectJoin
+ render_select_from: function to render a #GdaSqlSelectFrom
+ render_select_order: function to render a #GdaSqlSelectOrder
+ _gda_reserved1: 
+ _gda_reserved2: 
+ _gda_reserved3: 
+ _gda_reserved4: 
+ _gda_reserved5: 
+ _gda_reserved6: 
+ _gda_reserved7: 
+ _gda_reserved8: 
+
+<!-- ##### USER_FUNCTION GdaSqlRenderingValue ##### -->
+<para>
+  Rendering function type to render a #GValue
+</para>
+
+ value: the #GValue to render
+ context: the rendering contect
+ error: a place to store errors, or %NULL
+ Returns: a new string, or %NULL if an error occurred
+
+
+<!-- ##### USER_FUNCTION GdaSqlRenderingPSpecFunc ##### -->
+<para>
+  Rendering function type to render a #GdaSqlParamSpec
+</para>
+
+ pspec: #GdaSqlParamSpec to render
+ expr: #GdaSqlExpr which may hold the default value for the parameter, or %NULL
+ context: the rendering contect
+ is_default: pointer to a #gboolean which is set to TRUE if value should be considered as a default value
+ is_null: pointer to a #gboolean which is set to TRUE if value should be considered as NULL
+ error: a place to store errors, or %NULL
+ Returns: a new string, or %NULL if an error occurred
+
+
+<!-- ##### USER_FUNCTION GdaSqlRenderingExpr ##### -->
+<para>
+  Rendering function type to render a #GdaSqlExpr
+</para>
+
+ expr: #GdaSqlExpr to render
+ context: the rendering contect
+ is_default: pointer to a #gboolean which is set to TRUE if value should be considered as a default value
+ is_null: pointer to a #gboolean which is set to TRUE if value should be considered as NULL
+ error: a place to store errors, or %NULL
+ Returns: a new string, or %NULL if an error occurred
+
+
+<!-- ##### USER_FUNCTION GdaSqlRenderingFunc ##### -->
+<para>
+  Rendering function type to render any #GdaSqlAnyPart
+</para>
+
+ node: a #GdaSqlAnyPart pointer, to be cast to the correct type depending on which part the function has to render
+ context: the rendering contect
+ error: a place to store errors, or %NULL
+ Returns: a new string, or %NULL if an error occurred
+
+
+<!-- ##### FUNCTION gda_statement_to_sql_real ##### -->
+<para>
+
+</para>
+
+ stmt: 
+ context: 
+ error: 
+ Returns: 
+
+

Modified: trunk/libgda/gda-meta-struct.c
==============================================================================
--- trunk/libgda/gda-meta-struct.c	(original)
+++ trunk/libgda/gda-meta-struct.c	Tue Mar 10 21:36:05 2009
@@ -1510,7 +1510,8 @@
  * Get a list of all the #GdaMetaDbObject structures representing database objects in @mstruct. Note that
  * no #GdaMetaDbObject structure must not be modified.
  *
- * Returns: a new #GSList list of pointers which must be destroyed after usage using g_slist_free().
+ * Returns: a new #GSList list of pointers to #GdaMetaDbObject structures which must be destroyed after
+ * usage using g_slist_free(). The individual #GdaMetaDbObject must not be modified.
  */
 GSList *
 gda_meta_struct_get_all_db_objects (GdaMetaStruct *mstruct)

Modified: trunk/libgda/gda-statement.c
==============================================================================
--- trunk/libgda/gda-statement.c	(original)
+++ trunk/libgda/gda-statement.c	Tue Mar 10 21:36:05 2009
@@ -560,6 +560,19 @@
 static gchar *default_render_select_from (GdaSqlSelectFrom *from, GdaSqlRenderingContext *context, GError **error);
 static gchar *default_render_select_order (GdaSqlSelectOrder *order, GdaSqlRenderingContext *context, GError **error);
 
+/**
+ * gda_statement_to_sql_real
+ * @stmt: a #GdaStatement object
+ * @context: a #GdaSqlRenderingContext context
+ * @error: a place to store errors, or %NULL
+ *
+ * Renders @stmt to its SQL representation, using @context to specify how each part of @stmt must
+ * be rendered. This function is mainly used by database provider's implementations which require
+ * to specialize some aspects of SQL rendering to be adapted to the database,'s own SQL dialect
+ * (for example SQLite rewrites the 'FALSE' and 'TRUE' literals as '0' and 'NOT 0').
+ * 
+ * Returns: a new string, or %NULL if an error occurred
+ */
 gchar *
 gda_statement_to_sql_real (GdaStatement *stmt, GdaSqlRenderingContext *context, GError **error)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]