![]() |
![]() |
![]() |
GNOME Data Access 4.0 manual | ![]() |
---|---|---|---|---|
GdaStatement; enum GdaStatementSqlFlag; enum GdaStatementModelUsage; enum GdaStatementError; GdaStatement* gda_statement_new (void); GdaStatement* gda_statement_copy (GdaStatement *orig); gchar* gda_statement_serialize (GdaStatement *stmt); GdaStatement* gda_statement_deserialize (const gchar *str, GError **error); gboolean gda_statement_get_parameters (GdaStatement *stmt, GdaSet **out_params, GError **error); #define gda_statement_to_sql (stmt,params,error) gchar* gda_statement_to_sql_extended (GdaStatement *stmt, GdaConnection *cnc, GdaSet *params, GdaStatementSqlFlag flags, GSList **params_used, GError **error); GdaSqlStatementType gda_statement_get_statement_type (GdaStatement *stmt); gboolean gda_statement_is_useless (GdaStatement *stmt); gboolean gda_statement_check_structure (GdaStatement *stmt, GError **error); gboolean gda_statement_check_validity (GdaStatement *stmt, GdaConnection *cnc, GError **error); gboolean gda_statement_normalize (GdaStatement *stmt, GdaConnection *cnc, GError **error);
The GdaStatement represents a single SQL statement (multiple statements can be groupped in a GdaBatch object).
A GdaStatement can either be built "manually" by building a GdaSqlStatement structure, or from an SQL statement using a GdaSqlParser object.
A GdaConnection can use a GdaStatement to:
prepare it for a future execution, the preparation step involves converting the GdaStatement object into a structure used by the database's own API, see gda_connection_statement_prepare()
execute it using gda_connection_statement_execute_select() if it is known that the statement is a selection statement, gda_connection_statement_execute_non_select() if it is not a selection statement, or gda_connection_statement_execute() when the type of expected result is unknown.
Note that it is possible to use the same GdaStatement object at the same time with several GdaConnection objects.
typedef enum { GDA_STATEMENT_SQL_PRETTY = 1 << 0, GDA_STATEMENT_SQL_PARAMS_LONG = 1 << 1, GDA_STATEMENT_SQL_PARAMS_SHORT = 1 << 2, GDA_STATEMENT_SQL_PARAMS_AS_COLON = 1 << 3, GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR = 1 << 4, GDA_STATEMENT_SQL_PARAMS_AS_QMARK = 1 << 5, GDA_STATEMENT_SQL_PARAMS_AS_UQMARK = 1 << 6 } GdaStatementSqlFlag;
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.
typedef enum { GDA_STATEMENT_MODEL_RANDOM_ACCESS = 1 << 0, GDA_STATEMENT_MODEL_CURSOR_FORWARD = 1 << 1, GDA_STATEMENT_MODEL_CURSOR_BACKWARD = 1 << 2, GDA_STATEMENT_MODEL_CURSOR = GDA_STATEMENT_MODEL_CURSOR_FORWARD | GDA_STATEMENT_MODEL_CURSOR_BACKWARD, GDA_STATEMENT_MODEL_ALLOW_NOPARAM = 1 << 3 } GdaStatementModelUsage;
These flags specify how the GdaDataModel returned when executing a GdaStatement will be used
typedef enum { GDA_STATEMENT_PARSE_ERROR, GDA_STATEMENT_SYNTAX_ERROR, GDA_STATEMENT_NO_CNC_ERROR, GDA_STATEMENT_CNC_CLOSED_ERROR, GDA_STATEMENT_EXEC_ERROR, GDA_STATEMENT_PARAM_TYPE_ERROR, GDA_STATEMENT_PARAM_ERROR } GdaStatementError;
GdaStatement* gda_statement_new (void);
Creates a new GdaStatement object
Returns : | the new object |
GdaStatement* gda_statement_copy (GdaStatement *orig);
Copy constructor
orig : | a GdaStatement to make a copy of |
Returns : | a the new copy of orig |
gchar* gda_statement_serialize (GdaStatement *stmt);
Creates a string representing the contents of stmt.
stmt : | a GdaStatement object |
Returns : | a string containing the serialized version of stmt |
GdaStatement* gda_statement_deserialize (const gchar *str, GError **error);
Creates a new GdaStatement from a string
str : | a string containing a serialized version of a GdaStatement |
error : | a place to store errors, or NULL |
Returns : | a new GdaStatement object, or NULL if an error occurred |
gboolean gda_statement_get_parameters (GdaStatement *stmt, GdaSet **out_params, GError **error);
Get a new GdaSet object which groups all the execution parameters which stmt needs. This new object is returned though out_params.
Note that if stmt does not need any parameter, then out_params is set to NULL.
stmt : | a GdaStatement object |
out_params : | a place to store a new GdaSet object, or NULL |
error : | a place to store errors, or NULL |
Returns : | TRUE if no error occurred. |
#define gda_statement_to_sql(stmt,params,error) gda_statement_to_sql_extended ((stmt), NULL, (params), GDA_STATEMENT_SQL_PARAMS_SHORT, NULL, (error))
stmt : | |
params : | |
error : |
gchar* gda_statement_to_sql_extended (GdaStatement *stmt, GdaConnection *cnc, GdaSet *params, GdaStatementSqlFlag flags, GSList **params_used, GError **error);
Renders stmt as an SQL statement, with some control on how it is rendered.
If cnc is not NULL, then the rendered SQL will better be suited to be used by cnc (in particular it may include some SQL tweaks and/or proprietary extensions specific to the database engine used by cnc).
stmt : | a GdaStatement object |
cnc : | a GdaConnection object, or NULL |
params : | parameters contained in a single GdaSet object |
flags : | a set of flags to control the rendering |
params_used : | a place to store the list of actual GdaHolder objects in params used to do the rendering, or NULL |
error : | a place to store errors, or NULL |
Returns : | a new string if no error occurred |
GdaSqlStatementType gda_statement_get_statement_type (GdaStatement *stmt);
Get the type of statement held by stmt. It returns GDA_SQL_STATEMENT_NONE if stmt does not hold any statement
stmt : | a GdaStatement object |
Returns : | the statement type |
gboolean gda_statement_is_useless (GdaStatement *stmt);
Tells if stmt is composed only of spaces (that is it has no real SQL code), and is completely useless as such.
stmt : | a GdaStatement object |
Returns : | TRUE if executing stmt does nothing |
gboolean gda_statement_check_structure (GdaStatement *stmt, GError **error);
Checks that stmt's structure is correct.
stmt : | a GdaStatement object |
error : | a place to store errors, or NULL |
Returns : | TRUE if stmt's structure is correct |
gboolean gda_statement_check_validity (GdaStatement *stmt, GdaConnection *cnc, GError **error);
If cnc is not NULL then checks that every object (table, field, function) used in stmt actually exists in cnc's database
If cnc is NULL, then cleans anything related to cnc in stmt.
See gda_sql_statement_check_validity() for more information.
stmt : | a GdaStatement object |
cnc : | a GdaConnection object, or NULL |
error : | a place to store errors, or NULL |
Returns : | TRUE if every object actually exists in cnc's database |
gboolean gda_statement_normalize (GdaStatement *stmt, GdaConnection *cnc, GError **error);
"Normalizes" some parts of stmt, see gda_sql_statement_normalize() for more information.
stmt : | a GdaStatement object |
cnc : | a GdaConnection object |
error : | a place to store errors, or NULL |
Returns : | TRUE if no error occurred |
"structure" gpointer : Read / Write
This property changes or queries the internal GdaSqlStatement structure. A copy is made when either setting or getting that property.
void user_function (GdaStatement *gdastatement, GdaConnection *arg1, gboolean arg2, gpointer user_data) : Run First
gdastatement : | the object which received the signal. |
arg1 : | |
arg2 : | |
user_data : | user data set when the signal handler was connected. |
void user_function (GdaStatement *gdastatement, gpointer user_data) : Run First
This signal is emitted whenever the internal GdaSqlStatement structure has changed
gdastatement : | the object which received the signal. |
user_data : | user data set when the signal handler was connected. |