1 /* 2 * Copyright (C) 2008 - 2011 Vivien Malerba <malerba@gnome-db.org> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 21 #ifndef _GDA_STATEMENT_H_ 22 #define _GDA_STATEMENT_H_ 23 24 #include <glib-object.h> 25 #include <sql-parser/gda-statement-struct.h> 26 27 G_BEGIN_DECLS 28 29 #define GDA_TYPE_STATEMENT (gda_statement_get_type()) 30 #define GDA_STATEMENT(obj) G_TYPE_CHECK_INSTANCE_CAST (obj, gda_statement_get_type(), GdaStatement) 31 #define GDA_STATEMENT_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, gda_statement_get_type (), GdaStatementClass) 32 #define GDA_IS_STATEMENT(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, gda_statement_get_type ()) 33 34 /* error reporting */ 35 extern GQuark gda_statement_error_quark (void); 36 #define GDA_STATEMENT_ERROR gda_statement_error_quark () 37 38 /** 39 * GdaStatementError: 40 * @GDA_STATEMENT_PARSE_ERROR: 41 * @GDA_STATEMENT_SYNTAX_ERROR: 42 * @GDA_STATEMENT_NO_CNC_ERROR: 43 * @GDA_STATEMENT_CNC_CLOSED_ERROR: 44 * @GDA_STATEMENT_EXEC_ERROR: 45 * @GDA_STATEMENT_PARAM_TYPE_ERROR: 46 * @GDA_STATEMENT_PARAM_ERROR: 47 */ 48 typedef enum 49 { 50 GDA_STATEMENT_PARSE_ERROR, 51 GDA_STATEMENT_SYNTAX_ERROR, 52 GDA_STATEMENT_NO_CNC_ERROR, 53 GDA_STATEMENT_CNC_CLOSED_ERROR, 54 GDA_STATEMENT_EXEC_ERROR, 55 GDA_STATEMENT_PARAM_TYPE_ERROR, 56 GDA_STATEMENT_PARAM_ERROR 57 } GdaStatementError; 58 59 /** 60 * GdaStatementModelUsage: 61 * @GDA_STATEMENT_MODEL_RANDOM_ACCESS: access to the data model will be random (usually this will result in a data model completely stored in memory) 62 * @GDA_STATEMENT_MODEL_CURSOR_FORWARD: access to the data model will be done using a cursor moving forward 63 * @GDA_STATEMENT_MODEL_CURSOR_BACKWARD: access to the data model will be done using a cursor moving backward 64 * @GDA_STATEMENT_MODEL_CURSOR: access to the data model will be done using a cursor (moving both forward and backward) 65 * @GDA_STATEMENT_MODEL_ALLOW_NOPARAM: specifies that the data model should be executed even if some parameters required to execute it are invalid (in this case the data model will have no row, and will automatically be re-run when the missing parameters are once again valid) 66 * @GDA_STATEMENT_MODEL_OFFLINE: specifies that the data model's contents will be fully loaded into the client side (the memory of the process using Libgda), not requiring the server any more to access the data (the default behaviour is to access the server any time data is to be read, and data is cached in memory). This flag is useful only if used in conjunction with the GDA_STATEMENT_MODEL_RANDOM_ACCESS flag (otherwise an error will be returned). 67 * 68 * These flags specify how the #GdaDataModel returned when executing a #GdaStatement will be used 69 */ 70 typedef enum { 71 GDA_STATEMENT_MODEL_RANDOM_ACCESS = 1 << 0, 72 GDA_STATEMENT_MODEL_CURSOR_FORWARD = 1 << 1, 73 GDA_STATEMENT_MODEL_CURSOR_BACKWARD = 1 << 2, 74 GDA_STATEMENT_MODEL_CURSOR = GDA_STATEMENT_MODEL_CURSOR_FORWARD | GDA_STATEMENT_MODEL_CURSOR_BACKWARD, 75 GDA_STATEMENT_MODEL_ALLOW_NOPARAM = 1 << 3, 76 GDA_STATEMENT_MODEL_OFFLINE = 1 << 4 77 } GdaStatementModelUsage; 78 79 /** 80 * GdaStatementSqlFlag: 81 * @GDA_STATEMENT_SQL_PARAMS_AS_VALUES: rendering will replace parameters with their values 82 * @GDA_STATEMENT_SQL_PRETTY: rendering will include newlines and indentation to make it easy to read 83 * @GDA_STATEMENT_SQL_PARAMS_LONG: parameters will be rendered using the "/* name:<param_name> ... */" syntax 84 * @GDA_STATEMENT_SQL_PARAMS_SHORT: parameters will be rendered using the "##<param_name>..." syntax 85 * @GDA_STATEMENT_SQL_PARAMS_AS_COLON: parameters will be rendered using the ":<param_name>" syntax 86 * @GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR: parameters will be rendered using the "$<param_number>" syntax where parameters are numbered starting from 1 87 * @GDA_STATEMENT_SQL_PARAMS_AS_QMARK: parameters will be rendered using the "?<param_number>" syntax where parameters are numbered starting from 1 88 * @GDA_STATEMENT_SQL_PARAMS_AS_UQMARK: parameters will be rendered using the "?" syntax 89 * @GDA_STATEMENT_SQL_TIMEZONE_TO_GMT: time and timestamp with a timezone information are converted to GMT before rendering, and rendering does not show the timezone information 90 * 91 * Specifies rendering options 92 */ 93 typedef enum { 94 GDA_STATEMENT_SQL_PARAMS_AS_VALUES = 0, 95 GDA_STATEMENT_SQL_PRETTY = 1 << 0, 96 GDA_STATEMENT_SQL_PARAMS_LONG = 1 << 1, 97 GDA_STATEMENT_SQL_PARAMS_SHORT = 1 << 2, 98 GDA_STATEMENT_SQL_PARAMS_AS_COLON = 1 << 3, 99 GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR = 1 << 4, 100 GDA_STATEMENT_SQL_PARAMS_AS_QMARK = 1 << 5, 101 GDA_STATEMENT_SQL_PARAMS_AS_UQMARK = 1 << 6, 102 GDA_STATEMENT_SQL_TIMEZONE_TO_GMT = 1 << 7 103 } GdaStatementSqlFlag; 104 105 /* struct for the object's data */ 106 struct _GdaStatement 107 { 108 GObject object; 109 GdaStatementPrivate *priv; 110 }; 111 112 /* struct for the object's class */ 113 struct _GdaStatementClass 114 { 115 GObjectClass parent_class; 116 117 /* signals */ 118 void (*checked) (GdaStatement *stmt, GdaConnection *cnc, gboolean checked); 119 void (*reset) (GdaStatement *stmt); 120 121 /*< private >*/ 122 /* Padding for future expansion */ 123 void (*_gda_reserved1) (void); 124 void (*_gda_reserved2) (void); 125 void (*_gda_reserved3) (void); 126 void (*_gda_reserved4) (void); 127 }; 128 129 /** 130 * SECTION:gda-statement 131 * @short_description: Single SQL statement 132 * @title: GdaStatement 133 * @stability: Stable 134 * @see_also: #GdaBatch 135 * 136 * The #GdaStatement represents a single SQL statement (multiple statements can be grouped in a #GdaBatch object). 137 * 138 * A #GdaStatement can either be built by describing its constituing parts using a #GdaSqlBuilder object, 139 * or from an SQL statement using a #GdaSqlParser object. 140 * 141 * A #GdaConnection can use a #GdaStatement to: 142 * <itemizedlist> 143 * <listitem><para>prepare it for a future execution, the preparation step involves converting the #GdaStatement 144 * object into a structure used by the database's own API, see gda_connection_statement_prepare()</para></listitem> 145 * <listitem><para>execute it using gda_connection_statement_execute_select() if it is known that the statement is a 146 * selection statement, gda_connection_statement_execute_non_select() if it is not a selection statement, or 147 * gda_connection_statement_execute() when the type of expected result is unknown.</para></listitem> 148 * </itemizedlist> 149 * Note that it is possible to use the same #GdaStatement object at the same time with several #GdaConnection objects. 150 */ 151 152 GType gda_statement_get_type (void) G_GNUC_CONST; 153 GdaStatement *gda_statement_new (void); 154 GdaStatement *gda_statement_copy (GdaStatement *orig); 155 156 gchar *gda_statement_serialize (GdaStatement *stmt); 157 158 gboolean gda_statement_get_parameters (GdaStatement *stmt, GdaSet **out_params, GError **error); 159 #define gda_statement_to_sql(stmt,params,error) gda_statement_to_sql_extended ((stmt), NULL, (params), GDA_STATEMENT_SQL_PARAMS_SHORT, NULL, (error)) 160 gchar *gda_statement_to_sql_extended (GdaStatement *stmt, GdaConnection *cnc, 161 GdaSet *params, GdaStatementSqlFlag flags, 162 GSList **params_used, GError **error); 163 164 GdaSqlStatementType gda_statement_get_statement_type (GdaStatement *stmt); 165 gboolean gda_statement_is_useless (GdaStatement *stmt); 166 gboolean gda_statement_check_structure (GdaStatement *stmt, GError **error); 167 gboolean gda_statement_check_validity (GdaStatement *stmt, GdaConnection *cnc, GError **error); 168 gboolean gda_statement_normalize (GdaStatement *stmt, GdaConnection *cnc, GError **error); 169 170 G_END_DECLS 171 172 #endif 173