statement_execute

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 "+&lt;column number&gt;" 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.

Parameters:

this	a Connection
stmt	a Statement object
model_usage	in the case where stmt is a SELECT statement, specifies how the returned data model will be used
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

Returns:

a Object, or null if an error occurred