Misc API for database providers: GNOME Data Access 5 manual

## Misc API for database providers Misc API for database providers — Methods dedicated to implementing providers |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaServerOperation * | gda_server_operation_new ()
GdaSqlParser * | gda_server_provider_internal_get_parser ()
gboolean | gda_server_provider_perform_operation_default ()
GdaDataHandler * | gda_server_provider_get_data_handler_default ()
GdaDataHandler * | gda_server_provider_handler_use_default ()
GdaDataHandler * | gda_server_provider_handler_find ()
void | gda_server_provider_handler_declare ()
gchar * | gda_server_provider_find_file ()
gchar * | gda_server_provider_load_file_contents ()
void | gda_connection_internal_set_provider_data ()
gpointer | gda_connection_internal_get_provider_data ()
gpointer | gda_connection_internal_get_provider_data_error ()
void | gda_connection_add_event ()
GdaConnectionEvent * | gda_connection_add_event_string ()
void | gda_connection_clear_events_list ()
void | gda_connection_event_set_event_type ()
void | gda_connection_event_set_description ()
void | gda_connection_event_set_code ()
void | gda_connection_event_set_gda_code ()
void | gda_connection_event_set_source ()
void | gda_connection_event_set_sqlstate ()
void | gda_connection_add_prepared_statement ()
void | gda_connection_del_prepared_statement ()
GdaPStmt * | gda_connection_get_prepared_statement ()
void | gda_connection_internal_transaction_started ()
void | gda_connection_internal_transaction_rolledback ()
void | gda_connection_internal_transaction_committed ()
void | gda_connection_internal_statement_executed ()
void | gda_connection_internal_savepoint_added ()
void | gda_connection_internal_savepoint_rolledback ()
void | gda_connection_internal_savepoint_removed ()
void | gda_connection_internal_change_transaction_state ()
void | gda_connection_internal_reset_transaction_status ()
GdaConnection * | gda_connection_open_sqlite ()
gboolean | gda_meta_store_modify ()
gboolean | gda_meta_store_modify_v ()
gboolean | gda_meta_store_modify_with_context ()
void | gda_meta_store_set_identifiers_style ()
gboolean | (*GdaSqlReservedKeywordsFunc) ()
void | gda_meta_store_set_reserved_keywords_func ()
gboolean | gda_compute_dml_statements ()
GdaSqlStatement * | gda_compute_select_statement_from_update ()
GdaSqlStatement * | gda_rewrite_sql_statement_for_null_parameters ()
gboolean | gda_rewrite_statement_for_null_parameters ()
GdaSqlExpr * | gda_compute_unique_table_row_condition ()
GdaSqlExpr * | gda_compute_unique_table_row_condition_with_cnc ()
gboolean | gda_sql_any_part_check_structure ()
GdaSqlStatement * | gda_statement_rewrite_for_default_values ()
gchar * | gda_sql_identifier_force_quotes ()
gchar * | gda_sql_identifier_prepare_for_compare ()

## Types and Values

enum | GdaSqlIdentifierStyle

## Includes

    #include <libgda/providers-support/gda-pstmt.h>

## Description

The methods mentioned in this section are reserved for database providers implementations and should not bu used by developers outside that scope.

## Functions

### gda_server_operation_new ()

    GdaServerOperation *
    gda_server_operation_new (GdaServerOperationType op_type,
                              const gchar *xml_file);

IMPORTANT NOTE: Using this funtion is not the recommended way of creating a GdaServerOperation object, the correct way is to use `gda_server_provider_create_operation()`; this method is reserved for the database provider's implementation.

Creates a new GdaServerOperation object from the `xml_file` specifications

The `xml_file` must respect the DTD described in the "libgda-server-operation.dtd" file: its top node must be a <serv_op> tag.

#### Parameters

op_type | type of operation |
xml_file | a file which has the specifications for the GdaServerOperation object to create |

#### Returns

a new GdaServerOperation object

### gda_server_provider_internal_get_parser ()

    GdaSqlParser *
    gda_server_provider_internal_get_parser
                                   (GdaServerProvider *prov);

This is a factory method to get a unique instance of a GdaSqlParser object for each GdaServerProvider object Don't unref it.

#### Parameters

prov | a GdaServerProvider |

#### Returns

a GdaSqlParser.

[transfer none]

### gda_server_provider_perform_operation_default ()

    gboolean
    gda_server_provider_perform_operation_default
                                   (GdaServerProvider *provider,
                                    GdaConnection *cnc,
                                    GdaServerOperation *op,
                                    GError **error);

Performs the operation described by `op` , using the SQL from the rendering of the operation

#### Parameters

provider | a GdaServerProvider object |
cnc | a GdaConnection object which will be used to perform an action, or `NULL`. | [allow-none]
op | a GdaServerOperation object |
error | a place to store an error, or `NULL` |

#### Returns

`TRUE` if no error occurred

### gda_server_provider_get_data_handler_default ()

    GdaDataHandler *
    gda_server_provider_get_data_handler_default
                                   (GdaServerProvider *provider,
                                    GdaConnection *cnc,
                                    GType type,
                                    const gchar *dbms_type);

`gda_server_provider_get_data_handler_default` has been deprecated since version 5.2 and should not be used in newly-written code.

use `gda_server_provider_handler_use_default()` instead

Provides the implementation when the default Libgda's data handlers must be used

#### Parameters

provider | a server provider. |
cnc | a GdaConnection object, or `NULL`. | [allow-none]
type | a GType |
dbms_type | a DBMS type definition |

#### Returns

a GdaDataHandler, or `NULL`.

[transfer none]

### gda_server_provider_handler_use_default ()

    GdaDataHandler *
    gda_server_provider_handler_use_default
                                   (GdaServerProvider *provider,
                                    GType type);

Reserved to database provider's implementations. This method defines a default data handler for `provider` , and returns that GdaDataHandler.

[skip]

#### Parameters

provider | a server provider |
type | a GType |

#### Returns

a GdaDataHandler, or `NULL`.

[transfer none]

Since: 5.2

### gda_server_provider_handler_find ()

    GdaDataHandler *
    gda_server_provider_handler_find (GdaServerProvider *prov,
                                      GdaConnection *cnc,
                                      GType g_type,
                                      const gchar *dbms_type);

Reserved to database provider's implementations: get the GdaDataHandler associated to `prov` for connection `cnc` . You probably want to use `gda_server_provider_get_data_handler_g_type()`.

#### Parameters

prov | a GdaServerProvider |
cnc | a GdaConnection. | [allow-none]
g_type | a GType |
dbms_type | a database type. | [allow-none]

#### Returns

the requested GdaDataHandler, or `NULL` if none found.

[transfer none]

### gda_server_provider_handler_declare ()

    void
    gda_server_provider_handler_declare (GdaServerProvider *prov,
                                         GdaDataHandler *dh,
                                         GdaConnection *cnc,
                                         GType g_type,
                                         const gchar *dbms_type);

### gda_server_provider_find_file ()

    gchar *
    gda_server_provider_find_file (GdaServerProvider *prov,
                                   const gchar *inst_dir,
                                   const gchar *filename);

Finds the location of a `filename` . This function should only be used by database provider's implementations

#### Parameters

prov | a GdaServerProvider |
inst_dir | directory where `prov` is installed |
filename | name of the file to find |

#### Returns

the complete path to `filename` , or `NULL` if not found.

[transfer full]

### gda_server_provider_load_file_contents ()

    gchar *
    gda_server_provider_load_file_contents
                                   (const gchar *inst_dir,
                                    const gchar *data_dir,
                                    const gchar *filename);

Loads and returns the contents of `filename` , which is searched in several places This function should only be used by database provider's implementations

#### Parameters

inst_dir | directory where the database provider has been installed |
data_dir | DATA directory to look for ($prefix/share) |
filename | name of the file to load |

#### Returns

a new string containing `filename` 's contents, or `NULL` if not found or if an error occurred.

[transfer full]

### gda_connection_internal_set_provider_data ()

    void
    gda_connection_internal_set_provider_data
                                   (GdaConnection *cnc,
                                    gpointer data,
                                    GDestroyNotify destroy_func);

Note: calling this function more than once will not make it call `destroy_func` on any previously set opaque `data` , you'll have to do it yourself.

[skip]

#### Parameters

cnc | a GdaConnection object |
data | an opaque structure, known only to the provider for which `cnc` is opened |
destroy_func | function to call when the connection closes and `data` needs to be destroyed |

### gda_connection_internal_get_provider_data ()

    gpointer
    gda_connection_internal_get_provider_data
                                   (GdaConnection *cnc);

Get the opaque pointer previously set using `gda_connection_internal_set_provider_data()`. If it's not set, then add a connection event and returns `NULL`

[skip]

#### Parameters

cnc | a GdaConnection object |

#### Returns

the pointer to the opaque structure set using `gda_connection_internal_set_provider_data()`, or `NULL`.

[allow-none]

### gda_connection_internal_get_provider_data_error ()

    gpointer
    gda_connection_internal_get_provider_data_error
                                   (GdaConnection *cnc,
                                    GError **error);

Get the opaque pointer previously set using `gda_connection_internal_set_provider_data()`. If it's not set, then add a connection event and returns `NULL`

[skip]

#### Parameters

cnc | a GdaConnection object |
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

the pointer to the opaque structure set using `gda_connection_internal_set_provider_data()`, or `NULL`.

[allow-none]

Since: 5.0.2

### gda_connection_add_event ()

    void
    gda_connection_add_event (GdaConnection *cnc,
                              GdaConnectionEvent *event);

Adds an event to the given connection. This function is usually called by providers, to inform clients of events that happened during some operation.

As soon as a provider (or a client, it does not matter) calls this function with an `event` object which is an error, the connection object emits the "error" signal, to which clients can connect to be informed of events.

WARNING: the reference to the `event` object is stolen by this function!

#### Parameters

cnc | a GdaConnection object. |
event | is stored internally, so you don't need to unref it. | [transfer full]

### gda_connection_add_event_string ()

    GdaConnectionEvent *
    gda_connection_add_event_string (GdaConnection *cnc,
                                     const gchar *str,
                                     ...);

Adds a new error to the given connection object. This is just a convenience function that simply creates a GdaConnectionEvent and then calls gda_server_connection_add_error.

[skip]

#### Parameters

cnc | a GdaConnection object. |
str | a format string (see the printf(3) documentation). |
... | the arguments to insert in the error message. |

#### Returns

a new GdaConnectionEvent object, however the caller does not hold a reference to the returned object, and if need be the caller must call `g_object_ref()` on it.

[transfer none]

### gda_connection_clear_events_list ()

    void
    gda_connection_clear_events_list (GdaConnection *cnc);

This function lets you clear the list of GdaConnectionEvent's of the given connection.

#### Parameters

cnc | a GdaConnection object. |

### gda_connection_event_set_event_type ()

    void
    gda_connection_event_set_event_type (GdaConnectionEvent *event,
                                         GdaConnectionEventType type);

Sets `event` 's severity (from a simple notice to a fatal event) This function should not be called directly.

#### Parameters

event | a GdaConnectionEvent object |
type | the severity of the event |

### gda_connection_event_set_description ()

    void
    gda_connection_event_set_description (GdaConnectionEvent *event,
                                          const gchar *description);

Sets `event` 's `description` . This function should not be called directly.

#### Parameters

event | a GdaConnectionEvent. |
description | a description, or `NULL` (to unset current description if any). | [allow-none]

### gda_connection_event_set_code ()

    void
    gda_connection_event_set_code (GdaConnectionEvent *event,
                                   glong code);

Sets `event` 's code: the code is specific to the provider being used. If you want to have a common understanding of the event codes, use `gda_connection_event_get_gda_code()` instead.

This function should not be called directly

#### Parameters

event | a GdaConnectionEvent. |
code | a code. |

### gda_connection_event_set_gda_code ()

    void
    gda_connection_event_set_gda_code (GdaConnectionEvent *event,
                                       GdaConnectionEventCode code);

Sets `event` 's gda code: that code is standardized by the libgda library. If you want to specify the corresponding provider specific code, use `gda_connection_event_get_code()` or `gda_connection_event_get_sqlstate()` instead.

This function should not be called directly

#### Parameters

event | a GdaConnectionEvent |
code | a code |

### gda_connection_event_set_source ()

    void
    gda_connection_event_set_source (GdaConnectionEvent *event,
                                     const gchar *source);

Sets `event` 's `source` ; this function should not be called directly

#### Parameters

event | a GdaConnectionEvent. |
source | a source. |

### gda_connection_event_set_sqlstate ()

    void
    gda_connection_event_set_sqlstate (GdaConnectionEvent *event,
                                       const gchar *sqlstate);

Changes the SQLSTATE code of `event` , this function should not be called directly

Sets `event` 's SQL state.

#### Parameters

event | a GdaConnectionEvent. |
sqlstate | SQL state. |

### gda_connection_add_prepared_statement ()

    void
    gda_connection_add_prepared_statement (GdaConnection *cnc,
                                           GdaStatement *gda_stmt,
                                           GdaPStmt *prepared_stmt);

Declares that `prepared_stmt` is a prepared statement object associated to `gda_stmt` within the connection (meaning the connection increments the reference counter of `prepared_stmt` ).

If `gda_stmt` changes or is destroyed, the the association will be lost and the connection will lose the reference it has on `prepared_stmt` .

#### Parameters

cnc | a GdaConnection object |
gda_stmt | a GdaStatement object |
prepared_stmt | a prepared statement object (as a GdaPStmt object, or more likely a descendant) |

### gda_connection_del_prepared_statement ()

    void
    gda_connection_del_prepared_statement (GdaConnection *cnc,
                                           GdaStatement *gda_stmt);

Removes any prepared statement associated to `gda_stmt` in `cnc` : this undoes what `gda_connection_add_prepared_statement()` does.

#### Parameters

cnc | a GdaConnection object |
gda_stmt | a GdaStatement object |

### gda_connection_get_prepared_statement ()

    GdaPStmt *
    gda_connection_get_prepared_statement (GdaConnection *cnc,
                                           GdaStatement *gda_stmt);

Retrieves a pointer to an object representing a prepared statement for `gda_stmt` within `cnc` . The association must have been done using `gda_connection_add_prepared_statement()`.

#### Parameters

cnc | a GdaConnection object |
gda_stmt | a GdaStatement object |

#### Returns

the prepared statement, or `NULL` if no association exists.

[transfer none]

### gda_connection_internal_transaction_started ()

    void
    gda_connection_internal_transaction_started
                                   (GdaConnection *cnc,
                                    const gchar *parent_trans,
                                    const gchar *trans_name,
                                    GdaTransactionIsolation isol_level);

Internal functions to be called by database providers when a transaction has been started to keep track of the transaction status of the connection.

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
parent_trans | name of the parent transaction, or `NULL`. | [allow-none]
trans_name | transaction's name, or `NULL` |
isol_level | isolation level. |

### gda_connection_internal_transaction_rolledback ()

    void
    gda_connection_internal_transaction_rolledback
                                   (GdaConnection *cnc,
                                    const gchar *trans_name);

Internal functions to be called by database providers when a transaction has been rolled back to keep track of the transaction status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
trans_name | transaction's name, or `NULL`. | [allow-none]

### gda_connection_internal_transaction_committed ()

    void
    gda_connection_internal_transaction_committed
                                   (GdaConnection *cnc,
                                    const gchar *trans_name);

Internal functions to be called by database providers when a transaction has been committed to keep track of the transaction status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
trans_name | transaction's name, or `NULL`. | [allow-none]

### gda_connection_internal_statement_executed ()

    void
    gda_connection_internal_statement_executed
                                   (GdaConnection *cnc,
                                    GdaStatement *stmt,
                                    GdaSet *params,
                                    GdaConnectionEvent *error);

Internal functions to be called by database providers when a statement has been executed to keep track of the transaction status of the connection

[skip]

#### Parameters

cnc | a GdaConnection |
stmt | a GdaStatement which has been executed |
params | execution's parameters. | [allow-none]
error | a GdaConnectionEvent if the execution failed, or `NULL` |

### gda_connection_internal_savepoint_added ()

    void
    gda_connection_internal_savepoint_added
                                   (GdaConnection *cnc,
                                    const gchar *parent_trans,
                                    const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been added to keep track of the transaction status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
parent_trans | name of the parent transaction, or `NULL`. | [allow-none]
svp_name | savepoint's name, or `NULL` |

### gda_connection_internal_savepoint_rolledback ()

    void
    gda_connection_internal_savepoint_rolledback
                                   (GdaConnection *cnc,
                                    const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been rolled back to keep track of the transaction status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
svp_name | savepoint's name, or `NULL`. | [allow-none]

### gda_connection_internal_savepoint_removed ()

    void
    gda_connection_internal_savepoint_removed
                                   (GdaConnection *cnc,
                                    const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been removed to keep track of the transaction status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

[skip]

#### Parameters

cnc | a GdaConnection |
svp_name | savepoint's name, or `NULL`. | [allow-none]

### gda_connection_internal_change_transaction_state ()

    void
    gda_connection_internal_change_transaction_state
                                   (GdaConnection *cnc,
                                    GdaTransactionStatusState newstate);

Internal function to be called by database providers to force a transaction status change.

[skip]

#### Parameters

cnc | a GdaConnection |
newstate | the new state |

### gda_connection_internal_reset_transaction_status ()

    void
    gda_connection_internal_reset_transaction_status
                                   (GdaConnection *cnc);

Internal function to be called by database providers to reset the transaction status.

[skip]

#### Parameters

cnc | a GdaConnection |

### gda_connection_open_sqlite ()

    GdaConnection *
    gda_connection_open_sqlite (const gchar *directory,
                                const gchar *filename,
                                gboolean auto_unlink);

Opens an SQLite connection even if the SQLite provider is not installed, to be used by database providers which need a temporary database to store some information.

#### Parameters

directory | the directory the database file will be in, or `NULL` for the default TMP directory. | [allow-none]
filename | the database file name |
auto_unlink | if `TRUE`, then the database file will be removed afterwards |

#### Returns

a new GdaConnection, or `NULL` if an error occurred.

[transfer full]

### gda_meta_store_modify ()

    gboolean
    gda_meta_store_modify (GdaMetaStore *store,
                           const gchar *table_name,
                           GdaDataModel *new_data,
                           const gchar *condition,
                           GError **error,
                           ...);

Propagates an update to `store` , the update's contents is represented by `new_data` , this function is primarily reserved to database providers.

For example tell `store` to update its list of tables, `new_data` should contain the same columns as the "_tables" table of `store` , and contain one row per table in the store; there should not be any more argument after the `error` argument.

Now, to update only one table, the `new_data` data model should have one row for the table to update (or no row at all if the table does not exist anymore), and have values for the primary key of the "_tables" table of `store` , namely "table_catalog", "table_schema" and "table_name".

[skip]

#### Parameters

store | a GdaMetaStore object |
table_name | the name of the table to modify within `store` |
new_data | a GdaDataModel containing the new data to set in `table_name` , or `NULL` (treated as a data model with no row at all). | [nullable]
condition | SQL expression (which may contain variables) defining the rows which are being obsoleted by `new_data` , or `NULL`. | [nullable]
error | a place to store errors, or `NULL`. | [nullable]
... | a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentioned in `condition` . |

#### Returns

TRUE if no error occurred

### gda_meta_store_modify_v ()

    gboolean
    gda_meta_store_modify_v (GdaMetaStore *store,
                             const gchar *table_name,
                             GdaDataModel *new_data,
                             const gchar *condition,
                             gint nvalues,
                             const gchar **value_names,
                             const GValue **values,
                             GError **error);

Propagates an update to `store` , the update's contents is represented by `new_data` , this function is primarily reserved to database providers.

[rename-to gda_meta_store_modify]

#### Parameters

store | a GdaMetaStore object |
table_name | the name of the table to modify within `store` |
new_data | a GdaDataModel containing the new data to set in `table_name` , or `NULL` (treated as a data model with no row at all). | [nullable]
condition | SQL expression (which may contain variables) defining the rows which are being obsoleted by `new_data` , or `NULL`. | [nullable]
nvalues | number of values in `value_names` and `values` |
value_names | names of values. | [array length=nvalues]
values | values. | [array length=nvalues]
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

`TRUE` if no error occurred

Since: 4.2.6

### gda_meta_store_modify_with_context ()

    gboolean
    gda_meta_store_modify_with_context (GdaMetaStore *store,
                                        GdaMetaContext *context,
                                        GdaDataModel *new_data,
                                        GError **error);

Propagates an update to `store` , the update's contents is represented by `new_data` , this function is primarily reserved to database providers.

#### Parameters

store | a GdaMetaStore object |
context | a GdaMetaContext context describing what to modify in `store` . | [transfer none]
new_data | a GdaDataModel containing the new data to set in `table_name` , or `NULL` (treated as a data model with no row at all). | [transfer none][nullable]
error | a place to store errors, or `NULL` |

#### Returns

TRUE if no error occurred

### gda_meta_store_set_identifiers_style ()

    void
    gda_meta_store_set_identifiers_style (GdaMetaStore *store,
                                          GdaSqlIdentifierStyle style);

Specifies how `store` must handle SQL identifiers it has to store. This method is mainly used by database providers.

#### Parameters

store | a GdaMetaStore object |
style | a style |

Since: 4.2

### GdaSqlReservedKeywordsFunc ()

    gboolean
    (*GdaSqlReservedKeywordsFunc) (const gchar *word);

### gda_meta_store_set_reserved_keywords_func ()

    void
    gda_meta_store_set_reserved_keywords_func
                                   (GdaMetaStore *store,
                                    GdaSqlReservedKeywordsFunc func);

Specifies a function which `store` will use to determine if a keyword is an SQL reserved keyword or not.

This method is mainly used by database providers.

#### Parameters

store | a GdaMetaStore object |
func | a GdaSqlReservedKeywordsFunc function, or `NULL`. | [nullable][scope call]

Since: 4.2

### gda_compute_dml_statements ()

    gboolean
    gda_compute_dml_statements (GdaConnection *cnc,
                                GdaStatement *select_stmt,
                                gboolean require_pk,
                                GdaStatement **insert_stmt,
                                GdaStatement **update_stmt,
                                GdaStatement **delete_stmt,
                                GError **error);

Creates an INSERT, an UPDATE and a DELETE statement from a SELECT statement using the database metadata available in `cnc` 's meta store. Each statements are computed only if the corresponding place to store the created statement is not `NULL`.

#### Parameters

cnc | a GdaConnection |
select_stmt | a SELECT GdaStatement (compound statements not handled) |
require_pk | TRUE if the created statement have to use a primary key |
insert_stmt | a place to store the created INSERT statement, or `NULL`. | [nullable][transfer full]
update_stmt | a place to store the created UPDATE statement, or `NULL`. | [nullable][transfer full]
delete_stmt | a place to store the created DELETE statement, or `NULL`. | [nullable][transfer full]
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

`TRUE` if no error occurred

### gda_compute_select_statement_from_update ()

    GdaSqlStatement *
    gda_compute_select_statement_from_update
                                   (GdaStatement *update_stmt,
                                    GError **error);

Computes a SELECT statement which selects all the rows the `update_stmt` would update. Beware however that this GdaSqlStatement does not select anything (ie it would be rendered as "SELECT FROM ... WHERE ...") and before being usable, one needs to add some fields to actually select.

[skip]

#### Parameters

update_stmt | an UPDATE statement |
error | a place to store errors, or `NULL` |

#### Returns

a new GdaStatement if no error occurred, or `NULL` otherwise

### gda_rewrite_sql_statement_for_null_parameters ()

    GdaSqlStatement *
    gda_rewrite_sql_statement_for_null_parameters
                                   (GdaSqlStatement *sqlst,
                                    GdaSet *params,
                                    gboolean *out_modified,
                                    GError **error);

Modifies `sqlst` to take into account any parameter which might be `NULL`: if `sqlst` contains the equivalent of "xxx = <parameter definition>" and if that parameter is in `params` and its value is of type GDA_TYPE_NUL, then that part is replaced with "xxx IS NULL". It also handles the "xxx IS NOT NULL" transformation.

If `out_modified` is not `NULL`, then it will be set to `TRUE` if `sqlst` has been modified by this function, and to `FALSE` otherwise.

This function is used by provider's implementations to make sure one can use parameters with NULL values in statements without having to rewrite statements, as database usually don't consider that "xxx = NULL" is the same as "xxx IS NULL" when using parameters.

[skip]

#### Parameters

sqlst | a GdaSqlStatement. | [transfer full]
params | a GdaSet to be used as parameters when executing `stmt` |
out_modified | a place to store the boolean which tells if `stmt` has been modified or not, or `NULL`. | [nullable]
error | a place to store errors, or `NULL` |

#### Returns

the modified `sqlst` statement, or `NULL` if an error occurred.

[transfer full]

Since: 4.2.9

### gda_rewrite_statement_for_null_parameters ()

    gboolean
    gda_rewrite_statement_for_null_parameters
                                   (GdaStatement *stmt,
                                    GdaSet *params,
                                    GdaStatement **out_stmt,
                                    GError **error);

Modifies `stmt` to take into account any parameter which might be `NULL`: if `stmt` contains the equivalent of "xxx = <parameter definition>" and if that parameter is in `params` and its value is of type GDA_TYPE_NUL, then that part is replaced with "xxx IS NULL". It also handles the "xxx IS NOT NULL" transformation.

For example the following SELECT:

    SELECT * FROM data WHERE id = ##id::int::null AND name = ##name::string

in case the "id" parameter is set to NULL, is converted to:

    SELECT * FROM data WHERE id IS NULL AND name = ##name::string

if `out_stmt` is not `NULL`, then it will contain:

- the modified statement if some modifications were required and no error occured (the function returns `TRUE`)

- `NULL` if no modification to `stmt` were required and no erro occurred (the function returns `FALSE`)

- `NULL` if an error occured (the function returns `TRUE`)

This function is used by provider's implementations to make sure one can use parameters with NULL values in statements without having to rewrite statements, as database usually don't consider that "xxx = NULL" is the same as "xxx IS NULL" when using parameters.

#### Parameters

stmt | a GdaStatement. | [transfer none]
params | a GdaSet to be used as parameters when executing `stmt` |
out_stmt | a place to store the new GdaStatement, or `NULL`. | [transfer full][nullable]
error | a place to store errors, or `NULL` |

#### Returns

`TRUE` if `stmt` needs to be transformed to handle NULL parameters, and `FALSE` otherwise

Since: 4.2.9

### gda_compute_unique_table_row_condition ()

    GdaSqlExpr *
    gda_compute_unique_table_row_condition
                                   (GdaSqlStatementSelect *stsel,
                                    GdaMetaTable *mtable,
                                    gboolean require_pk,
                                    GError **error);

Computes a GdaSqlExpr expression which can be used in the WHERE clause of an UPDATE or DELETE statement when a row from the result of the `stsel` statement has to be modified.

[skip]

#### Parameters

stsel | a GdaSqlSelectStatement |
mtable | a GdaMetaTable |
require_pk | set to TRUE if a primary key ir required |
error | a place to store errors, or `NULL` |

#### Returns

a new GdaSqlExpr, or `NULL` if an error occurred.

### gda_compute_unique_table_row_condition_with_cnc ()

    GdaSqlExpr *
    gda_compute_unique_table_row_condition_with_cnc
                                   (GdaConnection *cnc,
                                    GdaSqlStatementSelect *stsel,
                                    GdaMetaTable *mtable,
                                    gboolean require_pk,
                                    GError **error);

Computes a GdaSqlExpr expression which can be used in the WHERE clause of an UPDATE or DELETE statement when a row from the result of the `stsel` statement has to be modified.

If `require_pk` is `TRUE` then this function will return a non `NULL` GdaSqlExpr only if it can use a primary key of `mtable` . If `require_pk` is `FALSE`, then it will try to use a primary key of `mtable` , and if none is available, it will use all the columns of `mtable` to compute a condition statement.

[skip]

#### Parameters

cnc | a GdaConnection, or `NULL`. | [nullable]
stsel | a GdaSqlSelectStatement |
mtable | a GdaMetaTable |
require_pk | set to `TRUE` if a primary key is required |
error | a place to store errors, or `NULL` |

#### Returns

a new GdaSqlExpr, or `NULL` if an error occurred.

Since: 4.0.3

### gda_sql_any_part_check_structure ()

    gboolean
    gda_sql_any_part_check_structure (GdaSqlAnyPart *node,
                                      GError **error);

Checks for any error in `node` 's structure to make sure it is valid. This is the same as `gda_sql_statement_check_structure()` but for individual GdaSqlAnyPart parts. This function is mainly for database provider's implementations

#### Parameters

node | a GdaSqlAnyPart pointer |
error | a place to store errors, or `NULL` |

#### Returns

TRUE if no error occurred

### gda_statement_rewrite_for_default_values ()

    GdaSqlStatement *
    gda_statement_rewrite_for_default_values
                                   (GdaStatement *stmt,
                                    GdaSet *params,
                                    gboolean remove,
                                    GError **error);

Rewrites `stmt` and creates a new GdaSqlStatement where all the variables which are to a DEFAULT value (as returned by `gda_holder_value_is_default()`) are either removed from the statement (if `remove` is `TRUE`) or replaced by the "DEFAULT" keyword (if `remove` is `FALSE`).

This function is only useful for database providers' implementations which have to deal with default values when executing statements, and is only relevant in the case of INSERT or UPDATE statements (in the latter case an error is returned if `remove` is `TRUE`).

For example the

    INSERT INTO mytable (id, name) VALUES (23, ##name::string)

is re-written into

    INSERT INTO mytable (id, name) VALUES (23, DEFAULT)

if `remove` is `FALSE` and into

    INSERT INTO mytable (id) VALUES (23)

if `remove` is `TRUE`.

[skip]

#### Parameters

stmt | a GdaStatement object |
params | a GdaSet containing the variable's values to be bound when executing `stmt` |
remove | set to `TRUE` if DEFAULT fields are removed, of `FALSE` if the "DEFAULT" keyword is used |
error | a place to store errors, or `NULL` |

#### Returns

a new GdaSqlStatement, or `NULL` if an error occurred

Since: 4.2

### gda_sql_identifier_force_quotes ()

    gchar *
    gda_sql_identifier_force_quotes (const gchar *str);

Add double quotes around the `str` identifier. This function is normally used only by database provider's implementation. Any double quote character is replaced by two double quote characters.

For other uses, see `gda_sql_identifier_quote()`.

#### Parameters

str | an SQL identifier |

Since: 5.0

### gda_sql_identifier_prepare_for_compare ()

    gchar *
    gda_sql_identifier_prepare_for_compare
                                   (gchar *str);

Prepares `str` to be compared:

- if surrounded by double quotes or single quotes, then just remove the quotes

- otherwise convert to lower case

The quoted string:

- must start and finish with the same single or double quotes character

- can contain the delimiter character (the single or double quotes) in the string if every instance of it is preceeded with a backslash character or with the delimiter character itself

This function is normally used only by database provider's implementation.

WARNING: `str` must NOT be a composed identifier (<part1>."<part2>" for example)

#### Parameters

str | a quoted string |

#### Returns

`str`

Since: 5.0

## Types and Values

### enum GdaSqlIdentifierStyle

Specifies how SQL identifiers are represented by a specific database

#### Members

GDA_SQL_IDENTIFIERS_LOWER_CASE | case insensitive SQL identifiers are represented in lower case (meaning that any SQL identifier which has a non lower case character is case sensitive) |
GDA_SQL_IDENTIFIERS_UPPER_CASE | case insensitive SQL identifiers are represented in upper case (meaning that any SQL identifier which has a non upper case character is case sensitive) |