GdaStatement

## GdaStatement GdaStatement — Single SQL statement |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaStatement;
    enum                GdaStatementSqlFlag;
    enum                GdaStatementModelUsage;
    enum                GdaStatementError;
    GdaStatement *      gda_statement_new                   (void);
    GdaStatement *      gda_statement_copy                  (GdaStatement *orig);
    gchar *             gda_statement_serialize             (GdaStatement *stmt);
    gboolean            gda_statement_get_parameters        (GdaStatement *stmt,
                                                             GdaSet **out_params,
                                                             GError **error);
    #define             gda_statement_to_sql                (stmt,
                                                             params,
                                                             error)
    gchar *             gda_statement_to_sql_extended       (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GdaSet *params,
                                                             GdaStatementSqlFlag flags,
                                                             GSList **params_used,
                                                             GError **error);
    GdaSqlStatementType gda_statement_get_statement_type    (GdaStatement *stmt);
    gboolean            gda_statement_is_useless            (GdaStatement *stmt);
    gboolean            gda_statement_check_structure       (GdaStatement *stmt,
                                                             GError **error);
    gboolean            gda_statement_check_validity        (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GError **error);
    gboolean            gda_statement_normalize             (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GdaStatement

## Properties

      "structure"                gpointer              : Read / Write

## Signals

      "checked"                                        : Run First
      "reset"                                          : Run First

## Description

The GdaStatement represents a single SQL statement (multiple statements can be grouped in a GdaBatch object).

A GdaStatement can either be built by describing its constituing parts using a GdaSqlBuilder object, or from an SQL statement using a GdaSqlParser object.

A GdaConnection can use a GdaStatement to:

- prepare it for a future execution, the preparation step involves converting the GdaStatement object into a structure used by the database's own API, see `gda_connection_statement_prepare()`

- execute it using `gda_connection_statement_execute_select()` if it is known that the statement is a selection statement, `gda_connection_statement_execute_non_select()` if it is not a selection statement, or `gda_connection_statement_execute()` when the type of expected result is unknown.

Note that it is possible to use the same GdaStatement object at the same time with several GdaConnection objects.

## Details

### GdaStatement

    typedef struct _GdaStatement GdaStatement;

### enum GdaStatementSqlFlag

    typedef enum {
    	GDA_STATEMENT_SQL_PARAMS_AS_VALUES   = 0,
            GDA_STATEMENT_SQL_PRETTY             = 1 << 0,
            GDA_STATEMENT_SQL_PARAMS_LONG        = 1 << 1,
            GDA_STATEMENT_SQL_PARAMS_SHORT       = 1 << 2,
            GDA_STATEMENT_SQL_PARAMS_AS_COLON    = 1 << 3,
            GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR   = 1 << 4,
            GDA_STATEMENT_SQL_PARAMS_AS_QMARK    = 1 << 5,
            GDA_STATEMENT_SQL_PARAMS_AS_UQMARK   = 1 << 6
    } GdaStatementSqlFlag;

Specifies rendering options

`GDA_STATEMENT_SQL_PARAMS_AS_VALUES` | rendering will replace parameters with their values
`GDA_STATEMENT_SQL_PRETTY` | rendering will include newlines and indentation to make it easy to read
`GDA_STATEMENT_SQL_PARAMS_LONG` | parameters will be rendered using the "/* name:<param_name> ... */" syntax
`GDA_STATEMENT_SQL_PARAMS_SHORT` | parameters will be rendered using the "##<param_name>..." syntax
`GDA_STATEMENT_SQL_PARAMS_AS_COLON` | parameters will be rendered using the ":<param_name>" syntax
`GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR` | parameters will be rendered using the "$<param_number>" syntax where parameters are numbered starting from 1
`GDA_STATEMENT_SQL_PARAMS_AS_QMARK` | parameters will be rendered using the "?<param_number>" syntax where parameters are numbered starting from 1
`GDA_STATEMENT_SQL_PARAMS_AS_UQMARK` | parameters will be rendered using the "?" syntax

### enum GdaStatementModelUsage

    typedef enum {
    	GDA_STATEMENT_MODEL_RANDOM_ACCESS   = 1 << 0,
    	GDA_STATEMENT_MODEL_CURSOR_FORWARD  = 1 << 1,
    	GDA_STATEMENT_MODEL_CURSOR_BACKWARD = 1 << 2,
    	GDA_STATEMENT_MODEL_CURSOR          = GDA_STATEMENT_MODEL_CURSOR_FORWARD | GDA_STATEMENT_MODEL_CURSOR_BACKWARD,
    	GDA_STATEMENT_MODEL_ALLOW_NOPARAM   = 1 << 3,
    	GDA_STATEMENT_MODEL_OFFLINE         = 1 << 4
    } GdaStatementModelUsage;

These flags specify how the GdaDataModel returned when executing a GdaStatement will be used

`GDA_STATEMENT_MODEL_RANDOM_ACCESS` | access to the data model will be random (usually this will result in a data model completely stored in memory)
`GDA_STATEMENT_MODEL_CURSOR_FORWARD` | access to the data model will be done using a cursor moving forward
`GDA_STATEMENT_MODEL_CURSOR_BACKWARD` | access to the data model will be done using a cursor moving backward
`GDA_STATEMENT_MODEL_CURSOR` | access to the data model will be done using a cursor (moving both forward and backward)
`GDA_STATEMENT_MODEL_ALLOW_NOPARAM` | specifies that the data model should be executed even if some parameters required to execute it are invalid (in this case the data model will have no row, and will automatically be re-run when the missing parameters are once again valid)
`GDA_STATEMENT_MODEL_OFFLINE` | specifies that the data model's contents will be fully loaded into the client side (the memory of the process using Libgda), not requiring the server any more to access the data (the default behaviour is to access the server any time data is to be read, and data is cached in memory). This flag is useful only if used in conjunction with the GDA_STATEMENT_MODEL_RANDOM_ACCESS flag (otherwise an error will be returned).

### enum GdaStatementError

    typedef enum {
    	GDA_STATEMENT_PARSE_ERROR,
    	GDA_STATEMENT_SYNTAX_ERROR,
    	GDA_STATEMENT_NO_CNC_ERROR,
    	GDA_STATEMENT_CNC_CLOSED_ERROR,
    	GDA_STATEMENT_EXEC_ERROR,
    	GDA_STATEMENT_PARAM_TYPE_ERROR,
    	GDA_STATEMENT_PARAM_ERROR
    } GdaStatementError;

### gda_statement_new ()

    GdaStatement *      gda_statement_new                   (void);

Creates a new GdaStatement object

Returns : | the new object

### gda_statement_copy ()

    GdaStatement *      gda_statement_copy                  (GdaStatement *orig);

Copy constructor

`orig` : | a GdaStatement to make a copy of
Returns : | a the new copy of `orig`. [transfer full]

### gda_statement_serialize ()

    gchar *             gda_statement_serialize             (GdaStatement *stmt);

Creates a string representing the contents of `stmt`.

`stmt` : | a GdaStatement object
Returns : | a string containing the serialized version of `stmt`

### gda_statement_get_parameters ()

    gboolean            gda_statement_get_parameters        (GdaStatement *stmt,
                                                             GdaSet **out_params,
                                                             GError **error);

Get a new GdaSet object which groups all the execution parameters which `stmt` needs. This new object is returned though `out_params`.

Note that if `stmt` does not need any parameter, then `out_params` is set to `NULL`.

`stmt` : | a GdaStatement object
`out_params` : | a place to store a new GdaSet object, or `NULL`. [out][allow-none][transfer full]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_statement_to_sql()

    #define             gda_statement_to_sql(stmt,params,error) gda_statement_to_sql_extended ((stmt), NULL, (params), GDA_STATEMENT_SQL_PARAMS_SHORT, NULL, (error))

### gda_statement_to_sql_extended ()

    gchar *             gda_statement_to_sql_extended       (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GdaSet *params,
                                                             GdaStatementSqlFlag flags,
                                                             GSList **params_used,
                                                             GError **error);

Renders `stmt` as an SQL statement, with some control on how it is rendered.

If `cnc` is not `NULL`, then the rendered SQL will better be suited to be used by `cnc` (in particular it may include some SQL tweaks and/or proprietary extensions specific to the database engine used by `cnc`): in this case the result is similar to calling `gda_connection_statement_to_sql()`.

`stmt` : | a GdaStatement object
`cnc` : | a GdaConnection object, or `NULL`. [allow-none]
`params` : | parameters contained in a single GdaSet object, or `NULL`. [allow-none]
`flags` : | a set of flags to control the rendering
`params_used` : | a place to store the list of actual GdaHolder objects in `params` used to do the rendering, or `NULL`. [element-type GdaHolder][out][transfer container][allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | a new string if no error occurred. [transfer full]

### gda_statement_get_statement_type ()

    GdaSqlStatementType gda_statement_get_statement_type    (GdaStatement *stmt);

Get the type of statement held by `stmt`. It returns GDA_SQL_STATEMENT_NONE if `stmt` does not hold any statement

`stmt` : | a GdaStatement object
Returns : | the statement type. [transfer none]

### gda_statement_is_useless ()

    gboolean            gda_statement_is_useless            (GdaStatement *stmt);

Tells if `stmt` is composed only of spaces (that is it has no real SQL code), and is completely useless as such.

`stmt` : | a GdaStatement object
Returns : | TRUE if executing `stmt` does nothing

### gda_statement_check_structure ()

    gboolean            gda_statement_check_structure       (GdaStatement *stmt,
                                                             GError **error);

Checks that `stmt`'s structure is correct.

`stmt` : | a GdaStatement object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if `stmt`'s structure is correct

### gda_statement_check_validity ()

    gboolean            gda_statement_check_validity        (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GError **error);

If `cnc` is not `NULL` then checks that every object (table, field, function) used in `stmt` actually exists in `cnc`'s database

If `cnc` is `NULL`, then cleans anything related to `cnc` in `stmt`.

See `gda_sql_statement_check_validity()` for more information.

`stmt` : | a GdaStatement object
`cnc` : | a GdaConnection object, or `NULL`. [allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if every object actually exists in `cnc`'s database

### gda_statement_normalize ()

    gboolean            gda_statement_normalize             (GdaStatement *stmt,
                                                             GdaConnection *cnc,
                                                             GError **error);

"Normalizes" some parts of `stmt`, see `gda_sql_statement_normalize()` for more information.

`stmt` : | a GdaStatement object
`cnc` : | a GdaConnection object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

## Property Details

### The `"structure"` property

      "structure"                gpointer              : Read / Write

## Signal Details

### The `"checked"` signal

    void                user_function                      (GdaStatement  *stmt,
                                                            GdaConnection *arg1,
                                                            gboolean       arg2,
                                                            gpointer       user_data)      : Run First

Gets emitted whenever the structure and contents of `stmt` have been verified (emitted after `gda_statement_check_validity()`).

`stmt` : | the GdaStatement object
`user_data` : | user data set when the signal handler was connected.

### The `"reset"` signal

    void                user_function                      (GdaStatement *stmt,
                                                            gpointer      user_data)      : Run First

Gets emitted whenever the `stmt` has changed

`stmt` : | the GdaStatement object
`user_data` : | user data set when the signal handler was connected.

## See Also

GdaBatch