GdaStatement

GdaStatement — Single SQL statement

Stability Level

Stable, unless otherwise indicated

Functions

Properties

gpointer structure Read / Write

Signals

Types and Values

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:

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