![]() |
![]() |
![]() |
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_connection (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 } 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 } 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_connection (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
.
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
|
structure
" property"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. |