![]() |
![]() |
![]() |
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.
indents the output for easier readability | |
use the <default value> /* ... */ syntax for each parameter | |
use the ##<param_name> syntax for each parameter when possible | |
use the :<param_name> syntax for each parameter, replacing any char not in [0-9A-Za-z] by '_' | |
use the $<param_number> syntax for each parameter (starting numbering at 1) | |
use the ?<param_number> syntax for each parameter (starting numbering at 1) | |
use the ? syntax for each parameter (no numbering) |
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
access to the data model will be random (usually this will result in a data model completely stored in memory) | |
access to the data model will be done using a cursor moving forward | |
access to the data model will be done using a cursor moving backward | |
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
|
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
.
|
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
|
a string containing a serialized version of a GdaStatement |
|
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
.
|
a GdaStatement object |
|
a place to store a new GdaSet object, or NULL
|
|
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))
|
|
|
|
|
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
).
|
a GdaStatement object |
|
a GdaConnection object, or NULL
|
|
parameters contained in a single GdaSet object |
|
a set of flags to control the rendering |
|
a place to store the list of actual GdaHolder objects in params used to do the rendering, or NULL
|
|
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
|
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.
|
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.
|
a GdaStatement object |
|
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.
|
a GdaStatement object |
|
a GdaConnection object, or NULL
|
|
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.
|
a GdaStatement object |
|
a GdaConnection object |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
"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.
"checked"
signalvoid user_function (GdaStatement *gdastatement, GdaConnection *arg1, gboolean arg2, gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
|
|
user data set when the signal handler was connected. |
"reset"
signalvoid user_function (GdaStatement *gdastatement, gpointer user_data) : Run First
This signal is emitted whenever the internal GdaSqlStatement structure has changed
|
the object which received the signal. |
|
user data set when the signal handler was connected. |