GdaStatement: GNOME Data Access 5 manual

## GdaStatement GdaStatement — Single SQL statement |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaStatement * | gda_statement_new ()
GdaStatement * | gda_statement_copy ()
gchar * | gda_statement_serialize ()
gboolean | gda_statement_get_parameters ()
#define | gda_statement_to_sql()
gchar * | gda_statement_to_sql_extended ()
GdaSqlStatementType | gda_statement_get_statement_type ()
gboolean | gda_statement_is_useless ()
gboolean | gda_statement_check_structure ()
gboolean | gda_statement_check_validity ()
gboolean | gda_statement_normalize ()

## Properties

gpointer | structure | Read / Write

## Signals

void | checked | Run First
void | reset | Run First

## Types and Values

| GdaStatement
enum | GdaStatementSqlFlag
enum | GdaStatementModelUsage
enum | GdaStatementError

## Object Hierarchy

        GObject
        ╰── GdaStatement

## Includes

    #include <libgda-report/gda-report-engine.h>

## 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.

## Functions

### 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

#### Parameters

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` .

#### Parameters

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`.

#### Parameters

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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

stmt | a GdaStatement object |
cnc | a GdaConnection object |
error | a place to store errors, or `NULL` |

#### Returns

TRUE if no error occurred

## Types and Values

### GdaStatement

    typedef struct _GdaStatement GdaStatement;

### enum GdaStatementSqlFlag

Specifies rendering options

#### Members

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 |
GDA_STATEMENT_SQL_TIMEZONE_TO_GMT | time and timestamp with a timezone information are converted to GMT before rendering, and rendering does not show the timezone information |

### enum GdaStatementModelUsage

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

#### Members

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

#### Members

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 |  |

## Property Details

### The `“structure”` property

      “structure”                gpointer

Owner: GdaStatement

Flags: Read / Write

## Signal Details

### The `“checked”` signal

    void
    user_function (GdaStatement  *gdastatement,
                   GdaConnection *arg1,
                   gboolean       arg2,
                   gpointer       user_data)

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

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“reset”` signal

    void
    user_function (GdaStatement *gdastatement,
                   gpointer      user_data)

Gets emitted whenever the statement has changed

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GdaBatch