GdaStatement

GdaStatement — Single SQL statement

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:

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 how the general rendering is done

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

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

stmt :

params :

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 GdaHolder][transfer container GdaHolder][allow-none GdaHolder]

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

This property changes or queries the internal GdaSqlStatement structure. A copy is made when either setting or getting that property.

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

This signal is emitted whenever the internal GdaSqlStatement structure has changed

stmt :

the GdaStatement object

user_data :

user data set when the signal handler was connected.

See Also

GdaBatch