![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
struct 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
); enum GdaDataSelectConditionType; gboolean gda_data_select_compute_modification_statements_ext (GdaDataSelect *model
,GdaDataSelectConditionType cond_type
,GError **error
); gboolean gda_data_select_compute_columns_attributes (GdaDataSelect *model
,GError **error
); gboolean gda_data_select_rerun (GdaDataSelect *model
,GError **error
); void gda_data_select_add_exception (GdaDataSelect *model
,GError *error
);
"auto-reset" gboolean : Read / Write "connection" GdaConnection* : Read / Write / Construct Only "delete-stmt" GdaStatement* : Read / Write "exec-params" GdaSet* : Read / Write / Construct Only "execution-delay" gdouble : Read / Write "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
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:
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;
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()
.
|
a GdaDataSelect data model |
|
an SQL condition (without the WHERE keyword) |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
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.
|
a GdaDataSelect data model |
|
a GdaSqlExpr expression. [transfer none] |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
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
|
a GdaDataSelect object |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred. |
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.
|
a GdaDataSelect data model |
|
a GdaStatement (INSERT, UPDATE or DELETE) |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred. |
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
|
a GdaDataSelect data model |
|
an SQL text |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred. |
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
This function is similar to calling gda_data_select_compute_modification_statements_ext with
cond_type
set to GDA_DATA_SELECT_COND_PK
|
a GdaDataSelect data model |
|
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 |
typedef enum { GDA_DATA_SELECT_COND_PK, GDA_DATA_SELECT_COND_ALL_COLUMNS } GdaDataSelectConditionType;
Defines what criteria gda_data_select_compute_modification_statements_ext()
uses
to uniquely identify a single row in a table when creating modification statements.
gboolean gda_data_select_compute_modification_statements_ext (GdaDataSelect *model
,GdaDataSelectConditionType cond_type
,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
|
a GdaDataSelect data model |
|
the type of condition for the modifications where one row only should be identified |
|
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 |
Since 4.2.9
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.
|
a GdaDataSelect data model |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
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.
|
a GdaDataSelect data model |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
Since 4.2
void gda_data_select_add_exception (GdaDataSelect *model
,GError *error
);
Add an exception to model
.
|
a GdaDataSelect |
|
an error to add as exception. [transfer full] |
Since 4.2.6
"auto-reset"
property "auto-reset" gboolean : Read / Write
Automatically re-run the SELECT statement if any parameter has changed since it was first executed.
Default value: FALSE
"connection"
property"connection" GdaConnection* : Read / Write / Construct Only
Connection from which this data model is created.
"delete-stmt"
property"delete-stmt" GdaStatement* : Read / Write
DELETE Statement to be executed to remove data.
"exec-params"
property"exec-params" GdaSet* : Read / Write / Construct Only
GdaSet used when the SELECT statement was executed.
"execution-delay"
property "execution-delay" gdouble : Read / Write
This property stores the execution delay which has been necessary to obtain the data
Allowed values: >= 0
Default value: 0
Since 4.2.9
"insert-stmt"
property"insert-stmt" GdaStatement* : Read / Write
INSERT Statement to be executed to add data.
"model-usage"
property "model-usage" guint : Read / Write / Construct Only
Determines how the data model may be used.
Allowed values: >= 1
Default value: 1
"prepared-stmt"
property"prepared-stmt" GdaPStmt* : Read / Write
Associated prepared statement (for internal usage).
"select-stmt"
property"select-stmt" GdaStatement* : Read
SELECT statement which was executed to yield to the data model.
"store-all-rows"
property "store-all-rows" gboolean : Read / Write
Tells if model has analyzed all the rows.
Default value: FALSE
"update-stmt"
property"update-stmt" GdaStatement* : Read / Write
UPDATE Statement to be executed to update data.