## Convenience functions

Convenience functions — Do quickly some actions

## Synopsis

    GdaServerOperation * gda_prepare_create_database        (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);
    gboolean            gda_perform_create_database         (const gchar *provider,
                                                             GdaServerOperation *op,
                                                             GError **error);
    GdaServerOperation * gda_prepare_drop_database          (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);
    gboolean            gda_perform_drop_database           (const gchar *provider,
                                                             GdaServerOperation *op,
                                                             GError **error);

    GdaDataModel*       gda_execute_select_command          (GdaConnection *cnc,
                                                             const gchar *sql,
                                                             GError **error);
    gint                gda_execute_non_select_command      (GdaConnection *cnc,
                                                             const gchar *sql,
                                                             GError **error);

    GdaServerOperation * gda_prepare_create_table           (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error,
                                                             ...);
    gboolean            gda_perform_create_table            (GdaServerOperation *op,
                                                             GError **error);
    GdaServerOperation * gda_prepare_drop_table             (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);
    gboolean            gda_perform_drop_table              (GdaServerOperation *op,
                                                             GError **error);

    gboolean            gda_insert_row_into_table           (GdaConnection *cnc,
                                                             const gchar *table,
                                                             GError **error,
                                                             ...);
    gboolean            gda_update_row_in_table             (GdaConnection *cnc,
                                                             const gchar *table,
                                                             const gchar *condition_column_name,
                                                             GValue *condition_value,
                                                             GError **error,
                                                             ...);
    gboolean            gda_delete_row_from_table           (GdaConnection *cnc,
                                                             const gchar *table,
                                                             const gchar *condition_column_name,
                                                             GValue *condition_value,
                                                             GError **error);

    GdaDataHandler *    gda_get_default_handler             (GType for_type);

## Description

## Details

### gda_prepare_create_database ()

    GdaServerOperation * gda_prepare_create_database        (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);

Creates a new GdaServerOperation object which contains the specifications required to create a database. Once these specifications provided, use `gda_perform_create_database()` to perform the database creation.

If `db_name` is left `NULL`, then the name of the database to create will have to be set in the returned GdaServerOperation using `gda_server_operation_set_value_at()`.

`provider` : | the database provider to use
`db_name` : | the name of the database to create, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | new GdaServerOperation object, or `NULL` if the provider does not support database creation

### gda_perform_create_database ()

    gboolean            gda_perform_create_database         (const gchar *provider,
                                                             GdaServerOperation *op,
                                                             GError **error);

Creates a new database using the specifications in `op`. `op` can be obtained using `gda_server_provider_create_operation()`, or `gda_prepare_create_database()`.

`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_prepare_create_database()`
`op` : | a GdaServerOperation object obtained using `gda_prepare_create_database()`
`error` : | a place to store en error, or `NULL`
Returns : | TRUE if no error occurred and the database has been created

### gda_prepare_drop_database ()

    GdaServerOperation * gda_prepare_drop_database          (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);

Creates a new GdaServerOperation object which contains the specifications required to drop a database. Once these specifications provided, use `gda_perform_drop_database()` to perform the database creation.

If `db_name` is left `NULL`, then the name of the database to drop will have to be set in the returned GdaServerOperation using `gda_server_operation_set_value_at()`.

`provider` : | the database provider to use
`db_name` : | the name of the database to drop, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | new GdaServerOperation object, or `NULL` if the provider does not support database destruction

### gda_perform_drop_database ()

    gboolean            gda_perform_drop_database           (const gchar *provider,
                                                             GdaServerOperation *op,
                                                             GError **error);

Destroys an existing database using the specifications in `op`. `op` can be obtained using `gda_server_provider_create_operation()`, or `gda_prepare_drop_database()`.

`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_prepare_drop_database()`
`op` : | a GdaServerOperation object obtained using `gda_prepare_drop_database()`
`error` : | a place to store en error, or `NULL`
Returns : | TRUE if no error occurred and the database has been destroyed

### gda_execute_select_command ()

    GdaDataModel*       gda_execute_select_command          (GdaConnection *cnc,
                                                             const gchar *sql,
                                                             GError **error);

Execute a SQL SELECT command over an opened connection.

`cnc` : | an opened connection
`sql` : | a query statament must begin with "SELECT"
`error` : | a place to store errors, or `NULL`
Returns : | a new GdaDataModel if succesfull, NULL otherwise

### gda_execute_non_select_command ()

    gint                gda_execute_non_select_command      (GdaConnection *cnc,
                                                             const gchar *sql,
                                                             GError **error);

`cnc` : |
`sql` : |
`error` : |
Returns : |

### gda_prepare_create_table ()

    GdaServerOperation * gda_prepare_create_table           (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error,
                                                             ...);

Add more arguments if the flag needs then:

GDA_EASY_CREATE_TABLE_FKEY_FLAG:

- string with the table's name referenced

- an integer with the number pairs "local_field", "referenced_field" used in the reference

- Pairs of "local_field", "referenced_field" to use, must match the number specified above.

- a string with the action for ON DELETE; can be: "RESTRICT", "CASCADE", "NO ACTION", "SET NULL" and "SET DEFAULT". Example: "ON UPDATE CASCADE".

- a string with the action for ON UPDATE (see above).

Create a GdaServerOperation object using an opened connection, taking three arguments, a colum's name the column's GType and GdaEasyCreateTableFlag flag, you need to finish the list using NULL.

You'll be able to modify the GdaServerOperation object to add custom options to the operation. When finish call gda_perform_create_table or gda_server_operation_perform_operation in order to execute the operation.

`cnc` : | an opened connection
`table_name` : | name of the table to create
`error` : | a place to store errors, or `NULL`
`...` : | group of three arguments for column's name, column's GType and a GdaEasyCreateTableFlag flag, finished with NULL
Returns : | a GdaServerOperation if no errors; NULL and set `error` otherwise

### gda_perform_create_table ()

    gboolean            gda_perform_create_table            (GdaServerOperation *op,
                                                             GError **error);

Performs a prepared GdaServerOperation to create a table. This could perform an operation created by gda_prepare_create_table or any other using the the GdaServerOperation API.

`op` : | a valid GdaServerOperation
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the table was created; FALSE and set `error` otherwise

### gda_prepare_drop_table ()

    GdaServerOperation * gda_prepare_drop_table             (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);

This is just a convenient function to create a GdaServerOperation to drop a table in an opened connection.

`cnc` : | an opened connection
`table_name` : | name of the table to drop
`error` : | a place to store errors, or `NULL`
Returns : | a new GdaServerOperation or NULL if couldn't create the opereration.

### gda_perform_drop_table ()

    gboolean            gda_perform_drop_table              (GdaServerOperation *op,
                                                             GError **error);

This is just a convenient function to perform a drop a table operation.

`op` : | a GdaServerOperation object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the table was dropped

### gda_insert_row_into_table ()

    gboolean            gda_insert_row_into_table           (GdaConnection *cnc,
                                                             const gchar *table,
                                                             GError **error,
                                                             ...);

This is a convenience function, which creates an INSERT statement and executes it using the values provided. It internally relies on variables which makes it immune to SQL injection problems.

The equivalent SQL command is: INSERT INTO <table> (<column_name> [,...]) VALUES (<column_name> = <new_value> [,...]).

`cnc` : | an opened connection
`table` : | table's name to insert into
`error` : | a place to store errors, or `NULL`
`...` : | a list of string/GValue pairs with the name of the column to use and the GValue pointer containing the value to insert for the column (value can be `NULL`), finished by a `NULL`. There must be at least one column name and value
Returns : | TRUE if no error occurred

### gda_update_row_in_table ()

    gboolean            gda_update_row_in_table             (GdaConnection *cnc,
                                                             const gchar *table,
                                                             const gchar *condition_column_name,
                                                             GValue *condition_value,
                                                             GError **error,
                                                             ...);

This is a convenience function, which creates an UPDATE statement and executes it using the values provided. It internally relies on variables which makes it immune to SQL injection problems.

The equivalent SQL command is: UPDATE <table> SET <column_name> = <new_value> [,...] WHERE <condition_column_name> = <condition_value>.

`cnc` : | an opened connection
`table` : | the table's name with the row's values to be updated
`condition_column_name` : | the name of the column to used in the WHERE condition clause
`condition_value` : | the `condition_column_type`'s GType
`error` : | a place to store errors, or `NULL`
`...` : | a list of string/GValue pairs with the name of the column to use and the GValue pointer containing the value to update the column to (value can be `NULL`), finished by a `NULL`. There must be at least one column name and value
Returns : | TRUE if no error occurred

### gda_delete_row_from_table ()

    gboolean            gda_delete_row_from_table           (GdaConnection *cnc,
                                                             const gchar *table,
                                                             const gchar *condition_column_name,
                                                             GValue *condition_value,
                                                             GError **error);

This is a convenience function, which creates a DELETE statement and executes it using the values provided. It internally relies on variables which makes it immune to SQL injection problems.

The equivalent SQL command is: DELETE FROM <table> WHERE <condition_column_name> = <condition_value>.

`cnc` : | an opened connection
`table` : | the table's name with the row's values to be updated
`condition_column_name` : | the name of the column to used in the WHERE condition clause
`condition_value` : | the `condition_column_type`'s GType
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_get_default_handler ()

    GdaDataHandler *    gda_get_default_handler             (GType for_type);

Obtain a pointer to a GdaDataHandler which can manage GValue values of type `for_type`. The returned data handler will be adapted to use the current locale information (for example dates will be formatted taking into accoutn the locale).

The returned pointer is `NULL` if there is no default data handler available for the `for_type` data type

`for_type` : | a GType type
Returns : | a GdaDataHandler which must not be modified or destroyed.. transfer none.