Executes stmt.
As stmt can, by design (and if not abused), contain only one SQL statement, the return object will either be: <
itemizedlist> <listitem><para>a DataSelect object (which is also a
DataModel) if stmt is a SELECT statement (usually a
GDA_SQL_STATEMENT_SELECT, see SqlStatementType) containing the results of the
SELECT. The resulting data model is by default read only, but modifications can be enabled, see the
DataSelect's documentation for more information.</para></listitem> <
listitem><para>a Set for any other SQL statement which correctly executed. In this case
(if the provider supports it), then the Set may contain value holders named: <itemizedlist
> <listitem><para>a (gint) Holder named "IMPACTED_ROWS"</para><
/listitem> <listitem><para>a (GObject) Holder named "EVENT" which contains a
ConnectionEvent</para></listitem> </itemizedlist></para><
/listitem> </itemizedlist>
If last_insert_row is not null and stmt is an INSERT statement, then it will
contain a new Set object composed of value holders named "+<column number>"
starting at column 0 which contain the actual inserted values. For example if a table is composed of an 'id' column which is auto
incremented and a 'name' column then the execution of a "INSERT INTO mytable (name) VALUES ('joe')" query will return a
Set with two holders: <itemizedlist> <listitem><para>one with the '+0' ID
which may for example contain 1 (note that its "name" property should be "id")</para></listitem> <listitem><para>
one with the '+1' ID which will contain 'joe' (note that its "name" property should be "name")</para></listitem> <
/itemizedlist> Note that the value pointer by last_insert_row may be null after the
function call if either the database provider does not support it, or if the last interted row could not be determined (for example with
SQLite if the table in which the data is inserted has the WITHOUT ROWID optimization).
This method may fail with a gda_server_provider_error domain error (see the ServerProviderError error codes).
Note1: If stmt is a SELECT statement which has some parameters and if params is null
, then the statement can't be executed and this method will return null.
Note2: If stmt is a SELECT statement which has some parameters and if params is not
null but contains some invalid parameters, then the statement can't be executed and this method will return
null, unless the model_usage has the GDA_STATEMENT_MODEL_ALLOW_NOPARAM flag.
Note3: If stmt is a SELECT statement which has some parameters and if params is not
null but contains some invalid parameters and if model_usage has the GDA_STATEMENT_MODEL_ALLOW_NOPARAM flag, then
the returned data model will contain no row but will have all the correct columns (even though some of the columns might report as
GDA_TYPE_NULL). In this case, if (after this method call) any of params' parameters change then the resulting data model will
re-run itself, see the GdaDataSelect's <link linkend="GdaDataSelect--auto-reset">auto-reset</link> property for more
information.
Note4: if model_usage does not contain the GDA_STATEMENT_MODEL_RANDOM_ACCESS or GDA_STATEMENT_MODEL_CURSOR_FORWARD flags,
then the default will be to return a random access data model
Note5: If stmt is a SELECT statement which returns blob values (of type gda_type_blob),
then an implicit transaction will have been started by the database provider, and it's up to the caller to close the transaction (which
will then be locked) once all the blob ressources have been liberated (when the returned data model is destroyed). See the section about
<link linkend="gen:blobs">Binary large objects (BLOBs)</link> for more information.
Also see the <link linkend="limitations">provider's limitations</link>, and the <link linkend="data-select">Advanced GdaDataSelect usage</link> sections.
| this | |
| stmt |
a Statement object |
| model_usage |
in the case where |
| last_insert_row |
a place to store a new Set object which contains the values of the last inserted row, or null |
| params |
a Set object (which can be obtained using get_parameters), or null |
|
a Object, or null if an error occurred |