GdaDataSelect

GdaDataSelect — Data models returned by the execution of a SELECT statement

Synopsis

                    GdaDataSelect;
enum                GdaDataSelectError;
gboolean            gda_data_select_set_row_selection_condition_sql
                                                        (GdaDataSelect *model,
                                                         const gchar *sql_where,
                                                         GError **error);
gboolean            gda_data_select_set_row_selection_condition
                                                        (GdaDataSelect *model,
                                                         GdaSqlExpr *expr,
                                                         GError **error);
gboolean            gda_data_select_compute_row_selection_condition
                                                        (GdaDataSelect *model,
                                                         GError **error);
gboolean            gda_data_select_set_modification_statement
                                                        (GdaDataSelect *model,
                                                         GdaStatement *mod_stmt,
                                                         GError **error);
gboolean            gda_data_select_set_modification_statement_sql
                                                        (GdaDataSelect *model,
                                                         const gchar *sql,
                                                         GError **error);
gboolean            gda_data_select_compute_modification_statements
                                                        (GdaDataSelect *model,
                                                         GError **error);
gboolean            gda_data_select_compute_columns_attributes
                                                        (GdaDataSelect *model,
                                                         GError **error);
gboolean            gda_data_select_rerun               (GdaDataSelect *model,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GdaDataSelect

Implemented Interfaces

GdaDataSelect implements GdaDataModel.

Properties

  "auto-reset"               gboolean              : Read / Write
  "connection"               GdaConnection*        : Read / Write / Construct Only
  "delete-stmt"              GdaStatement*         : Read / Write
  "exec-params"              GdaSet*               : Read / Write / Construct Only
  "insert-stmt"              GdaStatement*         : Read / Write
  "model-usage"              guint                 : Read / Write / Construct Only
  "prepared-stmt"            GdaPStmt*             : Read / Write
  "select-stmt"              GdaStatement*         : Read
  "store-all-rows"           gboolean              : Read / Write
  "update-stmt"              GdaStatement*         : Read / Write

Description

This data model implements the GdaDataModel interface and is the required base object when database providers implement a data model returned when a SELECT statement has been executed. As the GdaDataModel interface is implemented, consult the API to access and modify the data held in a GdaDataSelect object.

The default behaviour however is to disallow modifications, and this section documents how to characterize a GdaDataSelect to allow modifications. Once this is done, any modification done to the data model will be propagated to the modified table in the database using INSERT, UPDATE or DELETE statements.

After any modification, it is still possible to read values from the data model (even values for rows which have been modified or inserted). The data model might then execute some SELECT statement to fetch some actualized values. Note: there is a corner case where a modification made to a row would make the row not selected at first in the data model (for example is the original SELECT statement included a clause "WHERE id < 100" and the modification sets the "id" value to 110), then the row will still be in the data model even though it would not be if the SELECT statement which execution created the data model in the first place was re-run. This is illustrated in the schema below:

GdaDataSelect data model's contents after some modifications

Details

GdaDataSelect

typedef struct _GdaDataSelect GdaDataSelect;


enum GdaDataSelectError

typedef enum {
	GDA_DATA_SELECT_MODIFICATION_STATEMENT_ERROR,
	GDA_DATA_SELECT_MISSING_MODIFICATION_STATEMENT_ERROR,
	GDA_DATA_SELECT_CONNECTION_ERROR,
	GDA_DATA_SELECT_ACCESS_ERROR,
	GDA_DATA_SELECT_SQL_ERROR,
	GDA_DATA_SELECT_SAFETY_LOCKED_ERROR
} GdaDataSelectError;


gda_data_select_set_row_selection_condition_sql ()

gboolean            gda_data_select_set_row_selection_condition_sql
                                                        (GdaDataSelect *model,
                                                         const gchar *sql_where,
                                                         GError **error);

Specifies the SQL condition corresponding to the WHERE part of a SELECT statement which would return only 1 row (the expression of the primary key).

For example for a table created as "CREATE TABLE mytable (part1 int NOT NULL, part2 string NOT NULL, name string, PRIMARY KEY (part1, part2))", and if pmodel corresponds to the execution of the "SELECT name, part1, part2 FROM mytable", then the sensible value for sql_where would be "part1 = ##-1::int AND part2 = ##-2::string" because the values of the 'part1' field are located in pmodel's column number 1 and the values of the 'part2' field are located in pmodel's column number 2 and the primary key is composed of (part1, part2).

For more information about the syntax of the parameters (named "##-1::int" for example), see the GdaSqlParser documentation, and gda_data_select_set_modification_statement().

model :

a GdaDataSelect data model

sql_where :

an SQL condition (without the WHERE keyword)

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred

gda_data_select_set_row_selection_condition ()

gboolean            gda_data_select_set_row_selection_condition
                                                        (GdaDataSelect *model,
                                                         GdaSqlExpr *expr,
                                                         GError **error);

Offers the same features as gda_data_select_set_row_selection_condition_sql() but using a GdaSqlExpr structure instead of an SQL syntax.

model :

a GdaDataSelect data model

expr :

a GdaSqlExpr expression. [transfer none]

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred

gda_data_select_compute_row_selection_condition ()

gboolean            gda_data_select_compute_row_selection_condition
                                                        (GdaDataSelect *model,
                                                         GError **error);

Offers the same features as gda_data_select_set_row_selection_condition() but the expression is computed from the meta data associated to the connection being used when model was created.

NOTE1: make sure the meta data associated to the connection is up to date before using this method, see gda_connection_update_meta_store().

NOTE2: if the SELECT statement from which model has been created uses more than one table, or if the table used does not have any primary key, then this method will fail

model :

a GdaDataSelect object

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred.

gda_data_select_set_modification_statement ()

gboolean            gda_data_select_set_modification_statement
                                                        (GdaDataSelect *model,
                                                         GdaStatement *mod_stmt,
                                                         GError **error);

Informs model that it should allow modifications to the data in some columns and some rows using mod_stmt to propagate those modifications into the database.

If mod_stmt is:

  • an UPDATE statement, then all the rows in model will be modifyable

  • a DELETE statement, then it will be possible to delete rows in model

  • in INSERT statement, then it will be possible to add some rows to model

  • any other statement, then this method will return an error

This method can be called several times to specify different types of modification.

If mod_stmt is an UPDATE or DELETE statement then it should have a WHERE part which identifies a unique row in model (please note that this property can't be checked but may result in model behaving in an unpredictable way).

NOTE1: However, if the gda_data_select_set_row_selection_condition() or gda_data_select_set_row_selection_condition_sql() have been successfully be called before, the WHERE part of mod_stmt WILL be modified to use the row selection condition specified through one of these methods (please not that it is then possible to avoid specifying a WHERE part in mod_stmt then).

NOTE2: if gda_data_select_set_row_selection_condition() or gda_data_select_set_row_selection_condition_sql() have not yet been successfully be called before, then the WHERE part of mod_stmt will be used as if one of these functions had been called.

model :

a GdaDataSelect data model

mod_stmt :

a GdaStatement (INSERT, UPDATE or DELETE)

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred.

gda_data_select_set_modification_statement_sql ()

gboolean            gda_data_select_set_modification_statement_sql
                                                        (GdaDataSelect *model,
                                                         const gchar *sql,
                                                         GError **error);

Offers the same feature as gda_data_select_set_modification_statement() but using an SQL statement

model :

a GdaDataSelect data model

sql :

an SQL text

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred.

gda_data_select_compute_modification_statements ()

gboolean            gda_data_select_compute_modification_statements
                                                        (GdaDataSelect *model,
                                                         GError **error);

Makes model try to compute INSERT, UPDATE and DELETE statements to be used when modifying model's contents. Note: any modification statement set using gda_data_select_set_modification_statement() will first be unset

model :

a GdaDataSelect data model

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred. If FALSE is returned, then some modification statement may still have been computed

gda_data_select_compute_columns_attributes ()

gboolean            gda_data_select_compute_columns_attributes
                                                        (GdaDataSelect *model,
                                                         GError **error);

Computes correct attributes for each of model's columns, which includes the "NOT NULL" attribute, the default value, the precision and scale for numeric values.

model :

a GdaDataSelect data model

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred

gda_data_select_rerun ()

gboolean            gda_data_select_rerun               (GdaDataSelect *model,
                                                         GError **error);

Requests that model be re-run to have an updated result. If an error occurs, then model will not be changed.

model :

a GdaDataSelect data model

error :

a place to store errors, or NULL

Returns :

TRUE if no error occurred

Since 4.2

Property Details

The "auto-reset" property

  "auto-reset"               gboolean              : Read / Write

Automatically re-run the SELECT statement if any parameter has chanegd since it was first executed.

Default value: FALSE


The "connection" property

  "connection"               GdaConnection*        : Read / Write / Construct Only

Connection from which this data model is created.


The "delete-stmt" property

  "delete-stmt"              GdaStatement*         : Read / Write

DELETE Statement to be executed to remove data.


The "exec-params" property

  "exec-params"              GdaSet*               : Read / Write / Construct Only

GdaSet used when the SELECT statement was executed.


The "insert-stmt" property

  "insert-stmt"              GdaStatement*         : Read / Write

INSERT Statement to be executed to add data.


The "model-usage" property

  "model-usage"              guint                 : Read / Write / Construct Only

Determines how the data model may be used.

Allowed values: >= 1

Default value: 1


The "prepared-stmt" property

  "prepared-stmt"            GdaPStmt*             : Read / Write

Associated prepared statement (for internal usage).


The "select-stmt" property

  "select-stmt"              GdaStatement*         : Read

SELECT statement which was executed to yield to the data model.


The "store-all-rows" property

  "store-all-rows"           gboolean              : Read / Write

Tells if model has analyzed all the rows.

Default value: FALSE


The "update-stmt" property

  "update-stmt"              GdaStatement*         : Read / Write

UPDATE Statement to be executed to update data.

See Also

The Advanced GdaDataSelect usage section.