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);
GdaStatement*       gda_statement_deserialize           (const gchar *str,
                                                         GError **error);
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 groupped in a GdaBatch object).

A GdaStatement can either be built "manually" by building a GdaSqlStatement structure, 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_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;

These flags control how a GdaStatement will be rendered as SQL. If no "GDA_STATEMENT_SQL_PARAMS..." flag is specified, then for each parameter (variable) required by the statement, there must be a value provided when converting to SQL (through the params argument of the gda_statement_to_sql_extended() function), or an error will be reported.

GDA_STATEMENT_SQL_PRETTY

indents the output for easier readability

GDA_STATEMENT_SQL_PARAMS_LONG

use the <default value> /* ... */ syntax for each parameter

GDA_STATEMENT_SQL_PARAMS_SHORT

use the ##<param_name> syntax for each parameter when possible

GDA_STATEMENT_SQL_PARAMS_AS_COLON

use the :<param_name> syntax for each parameter, replacing any char not in [0-9A-Za-z] by '_'

GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR

use the $<param_number> syntax for each parameter (starting numbering at 1)

GDA_STATEMENT_SQL_PARAMS_AS_QMARK

use the ?<param_number> syntax for each parameter (starting numbering at 1)

GDA_STATEMENT_SQL_PARAMS_AS_UQMARK

use the ? syntax for each parameter (no numbering)

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


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

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

GdaStatement*       gda_statement_deserialize           (const gchar *str,
                                                         GError **error);

Creates a new GdaStatement from a string

str :

a string containing a serialized version of a GdaStatement

error :

a place to store errors, or NULL

Returns :

a new GdaStatement object, or NULL if an error occurred

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

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

stmt :

a GdaStatement object

cnc :

a GdaConnection object, or NULL

params :

parameters contained in a single GdaSet object

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

error :

a place to store errors, or NULL

Returns :

a new string if no error occurred

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

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

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  *gdastatement,
                                                        GdaConnection *arg1,
                                                        gboolean       arg2,
                                                        gpointer       user_data)         : Run First

gdastatement :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "reset" signal

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

This signal is emitted whenever the internal GdaSqlStatement structure has changed

gdastatement :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

See Also

GdaBatch