Methods - DML queries: GNOME Data Access 5 manual

## Methods - DML queries

This group of virtual methods is related to executing SQL queries of any kind. Libgda imposes that SQL statements be converted to one or more GdaStatement object(s), each GdaStatement object containing exactly one SQL statement (usually terminated by a semi colon). Each GdaStatement can then be prepared and/or executed individually.

Creating a GdaStatement object from some SQL is the job of a GdaSqlParser object.

### create_parser()

This method instantiates a GdaSqlParser object which is adapted to the database's specific SQL dialect. If the provider does not implement its own parser, then this method should not be implemented.

### statement_to_sql()

This method converts a GdaStatement object to its SQL representation. It should be implemented only if the default rendering is incorrect (to support some SQL specific dialect). The rendering process is decomposed into several rendering methods, and it is possible to override only some of the methods (see the PostgreSQL's implementation as an example).

### statement_prepare()

This method requests that a GdaStatement object be prepared for a future execution. It is called when gda_connection_statement_prepare() is called.

### statement_execute() - mandatory

This method actually executes a query represented by a GdaStatement object. See gda_connection_statement_execute() for more information, note that this method is also always the one called when any of the gda_connection_statement_execute*() methods are called.

A non NULL `exec_cb` parameter specifies that the user requests an asynchronous execution: the function has to return the NULL value immediately (it must not be blocking), and the `task_id` parameter must be set to contain a provider specific task ID. The `exec_cb` parameter points to a callback function (specified by the GdaConnection) which the provider has to call once the statement has been executed, using the same task ID which was defined when the statement_execute() function was called, and the `cb_data` specified when the statement_execute() function was called.

Note that if an asynchronous execution is requested, then the `stmt`, `params`, `col_types`, `last_inserted_row`, and `cb_data` parameters are supposed to exist and not be altered during the time the statement is executed (the GdaConnection ensures this) which means it's not necessary to make copies of them during the execution.

### handle_async()

This method is called by gda_connection_async_fetch_result().

This method, if implemented, is called to give the database provider a chance to execute some code in case an asynchronous statement's execution has been requested. Often providers will send some data over the network to the database server when the statement_execute() is called, and implement this virtual function as a way to get some data from the database server to see if the execution is terminated.

This function must return FALSE in case an error occurs, and TRUE if no error occurred (even if nothing was to be done).