Subclassing GdaDataSelect: GNOME Data Access 5 manual

## Subclassing GdaDataSelect Subclassing GdaDataSelect — Base class for all the data models returned by DBMS providers when a SELECT statement is executed |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | gda_data_select_take_row ()
GdaRow * | gda_data_select_get_stored_row ()
GdaConnection * | gda_data_select_get_connection ()
void | gda_data_select_set_columns ()
void | gda_column_set_name ()
void | gda_column_set_description ()
void | gda_column_set_dbms_type ()
void | gda_column_set_g_type ()
void | gda_column_set_allow_null ()
void | gda_column_set_auto_increment ()
void | gda_column_set_position ()
void | gda_column_set_default_value ()
gchar * | gda_alphanum_to_text ()
gchar * | gda_text_to_alphanum ()
gboolean | gda_data_model_iter_move_next_default ()
gboolean | gda_data_model_iter_move_prev_default ()
void | gda_row_invalidate_value ()
void | gda_row_invalidate_value_e ()
gboolean | gda_row_value_is_valid ()
gboolean | gda_row_value_is_valid_e ()

## Types and Values

struct | GdaDataSelectClass

## Includes

    #include <libgda/providers-support/gda-data-select-priv.h>

## Description

All database providers should subclass this class when returning a data model after the execution of a SELECT statement. Specifically it has the following features:

- Manages its list of GdaColumn using the list exported by the prepared statement object (GdaPStmt)

- Allows random or cursor based access

- Allows for efficient memory usage allowing the subclass to finely tune its memory usage

- Provides a generic mechanism for writable data models

See the Virtual methods for recordsets section for more information about how to implement the virtual methods of the subclassed object.

This section documents the methods available for the database provider's implementations.

## Functions

### gda_data_select_take_row ()

    void
    gda_data_select_take_row (GdaDataSelect *model,
                              GdaRow *row,
                              gint rownum);

Stores `row` into `model` , externally advertized at row number `rownum` (if no row has been removed). The reference to `row` is stolen.

This function is used by database provider's implementations

#### Parameters

model | a GdaDataSelect data model |
row | a GdaRow row. | [transfer full]
rownum | "external" advertized row number |

### gda_data_select_get_stored_row ()

    GdaRow *
    gda_data_select_get_stored_row (GdaDataSelect *model,
                                    gint rownum);

Get the GdaRow object stored within `model` at row `rownum` (without taking care of removed rows)

#### Parameters

model | a GdaDataSelect data model |
rownum | "external" advertized row number |

#### Returns

the requested GdaRow, or `NULL` if not found.

[transfer none]

### gda_data_select_get_connection ()

    GdaConnection *
    gda_data_select_get_connection (GdaDataSelect *model);

Get a pointer to the GdaConnection object which was used when `model` was created (and which may be used internally by `model` ).

#### Parameters

model | a GdaDataSelect data model |

#### Returns

a pointer to the GdaConnection, or `NULL`.

[transfer none]

### gda_data_select_set_columns ()

    void
    gda_data_select_set_columns (GdaDataSelect *model,
                                 GSList *columns);

Makes `columns` the list of columns for `model` . Both the list and each GdaColumn object in the list are 'stolen' by `model` (ie. when this function returns the caller should not use anymore the list or each column object in it). This method should not be used directly, it is used by database provider's implementations.

#### Parameters

model | a GdaDataSelect data model |
columns | a lis of GdaColumn objects. | [transfer full]

Since: 4.2.1

### gda_column_set_name ()

    void
    gda_column_set_name (GdaColumn *column,
                         const gchar *name);

Sets the name of `column` to `name` .

#### Parameters

column | a GdaColumn. |
name | the new name of `column` . |

### gda_column_set_description ()

    void
    gda_column_set_description (GdaColumn *column,
                                const gchar *title);

Sets the column's description

#### Parameters

column | a GdaColumn. |
title | title name. |

### gda_column_set_dbms_type ()

    void
    gda_column_set_dbms_type (GdaColumn *column,
                              const gchar *dbms_type);

Defines `column` 's database type

#### Parameters

column | a GdaColumn |
dbms_type | a string |

### gda_column_set_g_type ()

    void
    gda_column_set_g_type (GdaColumn *column,
                           GType type);

Sets the type of `column` to `type` .

#### Parameters

column | a GdaColumn. |
type | the new type of `column` . |

### gda_column_set_allow_null ()

    void
    gda_column_set_allow_null (GdaColumn *column,
                               gboolean allow);

Sets the 'allow null' flag of the given column.

#### Parameters

column | a GdaColumn. |
allow | whether the given column should allows null values or not. |

### gda_column_set_auto_increment ()

    void
    gda_column_set_auto_increment (GdaColumn *column,
                                   gboolean is_auto);

Sets the auto increment flag for the given column.

#### Parameters

column | a GdaColumn. |
is_auto | auto increment status. |

### gda_column_set_position ()

    void
    gda_column_set_position (GdaColumn *column,
                             gint position);

Sets the position of the column refer to in the containing data model.

#### Parameters

column | a GdaColumn. |
position | the wanted position of the column in the containing data model. |

### gda_column_set_default_value ()

    void
    gda_column_set_default_value (GdaColumn *column,
                                  const GValue *default_value);

Sets `column` 's default GValue.

#### Parameters

column | a GdaColumn. |
default_value | default GValue for the column. | [allow-none]

### gda_alphanum_to_text ()

    gchar *
    gda_alphanum_to_text (gchar *text);

Does the opposite of `gda_text_to_alphanum()`, in the same string

#### Parameters

text | a string |

#### Returns

`text` if conversion succeeded or `NULL` if an error occurred

### gda_text_to_alphanum ()

    gchar *
    gda_text_to_alphanum (const gchar *text);

The "encoding" consists in replacing non alphanumeric character with the string "__gdaXX" where XX is the hex. representation of the non alphanumeric char.

#### Parameters

text | the text to convert |

#### Returns

a new string

### gda_data_model_iter_move_next_default ()

    gboolean
    gda_data_model_iter_move_next_default (GdaDataModel *model,
                                           GdaDataModelIter *iter);

Method reserved to GdaDataModelIter implementations, should not be called directly.

[skip]

#### Parameters

model | a GdaDataModel |
iter | a GdaDataModelIter iterating in `model` |

#### Returns

`TRUE` if `iter` was moved correctly.

### gda_data_model_iter_move_prev_default ()

    gboolean
    gda_data_model_iter_move_prev_default (GdaDataModel *model,
                                           GdaDataModelIter *iter);

Method reserved to GdaDataModelIter implementations, should not be called directly.

[skip]

#### Parameters

model | a GdaDataModel |
iter | a GdaDataModelIter iterating in `model` |

#### Returns

`TRUE` if `iter` was moved correctly.

### gda_row_invalidate_value ()

    void
    gda_row_invalidate_value (GdaRow *row,
                              GValue *value);

Marks `value` as being invalid. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

#### Parameters

row | a GdaRow |
value | a GValue belonging to `row` (obtained with `gda_row_get_value()`). |

### gda_row_invalidate_value_e ()

    void
    gda_row_invalidate_value_e (GdaRow *row,
                                GValue *value,
                                GError *error);

Marks `value` as being invalid. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

#### Parameters

row | a GdaRow |
value | a GValue belonging to `row` (obtained with `gda_row_get_value()`). |
error | the error which lead to the invalidation. | [allow-none][transfer full]

Since: 4.2.10

### gda_row_value_is_valid ()

    gboolean
    gda_row_value_is_valid (GdaRow *row,
                            GValue *value);

Tells if `value` has been marked as being invalid by `gda_row_invalidate_value()`. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

#### Parameters

row | a GdaRow. |
value | a GValue belonging to `row` (obtained with `gda_row_get_value()`). |

#### Returns

`TRUE` if `value` is valid

### gda_row_value_is_valid_e ()

    gboolean
    gda_row_value_is_valid_e (GdaRow *row,
                              GValue *value,
                              GError **error);

Tells if `value` has been marked as being invalid by `gda_row_invalidate_value()`. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

#### Parameters

row | a GdaRow. |
value | a GValue belonging to `row` (obtained with `gda_row_get_value()`). |
error | a place to store the invalid error, or `NULL`. | [allow-none]

#### Returns

`TRUE` if `value` is valid

Since: 4.2.10

## Types and Values

### struct GdaDataSelectClass

    struct GdaDataSelectClass {
    	GObjectClass      parent_class;

    	/* GDA_DATA_MODEL_ACCESS_RANDOM */
    	gint             (*fetch_nb_rows) (GdaDataSelect *model);
    	gboolean         (*fetch_random)  (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
    	gboolean         (*store_all)     (GdaDataSelect *model, GError **error);

    	/* GDA_STATEMENT_MODEL_CURSOR_* */
    	gboolean         (*fetch_next)    (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
    	gboolean         (*fetch_prev)    (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
    	gboolean         (*fetch_at)      (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
    };

## See Also

GdaDataModel and GdaDataSelect