GdaRecordset

Name

GdaRecordset -- Recordset (set of rows returned by providers) management

Synopsis



#define     GDA_RECORDSET_INVALID_POSITION
GdaRecordset* gda_recordset_new             (void);
void        gda_recordset_free              (GdaRecordset *rs);
void        gda_recordset_set_name          (GdaRecordset *rs,
                                             gchar *name);
void        gda_recordset_get_name          (GdaRecordset *rs,
                                             gchar *name);
void        gda_recordset_close             (GdaRecordset *rs);
GdaField*   gda_recordset_field_name        (GdaRecordset *rs,
                                             gchar *name);
GdaField*   gda_recordset_field_idx         (GdaRecordset *rs,
                                             gint idx);
gboolean    gda_recordset_bof               (GdaRecordset *rs);
gboolean    gda_recordset_eof               (GdaRecordset *rs);
gulong      gda_recordset_move              (GdaRecordset *rs,
                                             gint count,
                                             gpointer bookmark);
gulong      gda_recordset_move_first        (GdaRecordset *rs);
gulong      gda_recordset_move_last         (GdaRecordset *rs);
gulong      gda_recordset_move_next         (GdaRecordset *rs);
gulong      gda_recordset_move_prev         (GdaRecordset *rs);
gint        gda_recordset_rowsize           (GdaRecordset *rs);
gulong      gda_recordset_affected_rows     (GdaRecordset *rs);
gint        gda_recordset_open              (GdaRecordset *rs,
                                             GdaCommand *cmd,
                                             GDA_CursorType cursor_type,
                                             GDA_LockType lock_type,
                                             gulong options);
gint        gda_recordset_open_txt          (GdaRecordset *rs,
                                             gchar *txt,
                                             GDA_CursorType cursor_type,
                                             GDA_LockType lock_type,
                                             gulong options);
gint        gda_recordset_set_connection    (GdaRecordset *rs,
                                             GdaConnection *cnc);
GdaConnection* gda_recordset_get_connection (GdaRecordset *rs);
gint        gda_recordset_add_field         (GdaRecordset *rs,
                                             GdaField *field);
gint        gda_recordset_create            (GdaRecordset *rs);
GDA_CursorLocation gda_recordset_get_cursorloc
                                            (GdaRecordset *rs);
void        gda_recordset_set_cursorloc     (GdaRecordset *rs,
                                             GDA_CursorLocation loc);
GDA_CursorType gda_recordset_get_cursortype (GdaRecordset *rs);
void        gda_recordset_set_cursortype    (GdaRecordset *rs,
                                             GDA_CursorType type);

Description

Details

GDA_RECORDSET_INVALID_POSITION

#define GDA_RECORDSET_INVALID_POSITION 0xffffffff


gda_recordset_new ()

GdaRecordset* gda_recordset_new             (void);

Allocates space for a new recordset.

Returns :

the allocated recordset object


gda_recordset_free ()

void        gda_recordset_free              (GdaRecordset *rs);

This function frees all memory allocated by the recordset and destroys all associations with commands and connections.

rs :

the recordset which should be destroyed.


gda_recordset_set_name ()

void        gda_recordset_set_name          (GdaRecordset *rs,
                                             gchar *name);

rs :

name :


gda_recordset_get_name ()

void        gda_recordset_get_name          (GdaRecordset *rs,
                                             gchar *name);

rs :

name :


gda_recordset_close ()

void        gda_recordset_close             (GdaRecordset *rs);

This function closes the recordset and frees the memory occupied by the actual data items. The recordset can be opened again, doing the same query as before. It is guaranteeed that the data cached by the recordset is refetched from the server. Use this function is some characteristics of the recordset must be changed

rs :

the recordset to close


gda_recordset_field_name ()

GdaField*   gda_recordset_field_name        (GdaRecordset *rs,
                                             gchar *name);

Returns a pointer to the field with the name name of the current row of the recordset.

rs :

the recordset

name :

Returns :

a pointer to a field structor or NULL if idx is out of range


gda_recordset_field_idx ()

GdaField*   gda_recordset_field_idx         (GdaRecordset *rs,
                                             gint idx);

Returns a pointer to the field at position idx of the current row of the recordset.

rs :

the recordset

idx :

the index of the field in the current row

Returns :

a pointer to a field structor or NULL if idx is out of range


gda_recordset_bof ()

gboolean    gda_recordset_bof               (GdaRecordset *rs);

This function is used to check if the recordset cursor is beyond the first row. If this function returns TRUE any of the functions which actually returns the value of a field an error is returned because the cursor doesn't point to a row.

rs :

recordset to be checked

Returns :

TRUE if the cursor is beyond the first record or the recordset is empty, FALSE otherwise.


gda_recordset_eof ()

gboolean    gda_recordset_eof               (GdaRecordset *rs);

This function is used to check if the recordset cursor is after the last row. If this function returns TRUE any of the functions which actually returns the value of a field an error is returned because the cursor doesn't point to a row.

rs :

recordset to be checked

Returns :

TRUE if the cursor is after the last record or the recordset is empty, FALSE otherwise.


gda_recordset_move ()

gulong      gda_recordset_move              (GdaRecordset *rs,
                                             gint count,
                                             gpointer bookmark);

Moves the cursor of the recordset forward or backward. count is the number of records to move. If count is negative the cursor is moved towards the beginning. The function causes the recordset to actually fetch records from the data source. Each fetch from the data source fetches cachesize rows in one turn. A maximum of maxrows rows can be fetched.

If the cursor is on the second row and the count parameter is -10, then the cursor is position in front of the first record available. gda_rcordset_bof() will return TRUE and the return value of the function is two, because the cursor actually moved two records.

rs :

the recordset

count :

The number of records to skip

bookmark :

if not NULL, the cursor is positioned relative to the record described by this paramter. seee gda_recordset_get_bookmark() how to get bookmark values for records.

Returns :

the number of the record the cursor is addressing after the move or GDA_RECORDSET_INVALID_POSITION if there was an error fetching the rows.


gda_recordset_move_first ()

gulong      gda_recordset_move_first        (GdaRecordset *rs);

Moves the cursor of the recordset to the first record.

If the cursor is already on the the first record nothing happen.

rs :

the recordset

Returns :

the position of the cursor, or GDA_RECORDSET_INVALID_POSITION if there was an error.


gda_recordset_move_last ()

gulong      gda_recordset_move_last         (GdaRecordset *rs);

Moves the cursor of the recordset to the last record.

If the cursor is already on the the last record nothing happen.

rs :

the recordset

Returns :

the position of the cursor, or GDA_RECORDSET_INVALID_POSITION if there was an error.


gda_recordset_move_next ()

gulong      gda_recordset_move_next         (GdaRecordset *rs);

Moves the cursor of the recordset to the next record.

Has the same effect as calling gda_recordset_move() with count set to 1.

rs :

the recordset

Returns :

the position of the cursor, or GDA_RECORDSET_INVALID_POSITION if there was an error.


gda_recordset_move_prev ()

gulong      gda_recordset_move_prev         (GdaRecordset *rs);

rs :

the recordset

Returns :


gda_recordset_rowsize ()

gint        gda_recordset_rowsize           (GdaRecordset *rs);

rs :

the recordset

Returns :

the number of fields in a row of the current recordset


gda_recordset_affected_rows ()

gulong      gda_recordset_affected_rows     (GdaRecordset *rs);

Return the number of affected rows in the recordset

rs :

the recordset

Returns :


gda_recordset_open ()

gint        gda_recordset_open              (GdaRecordset *rs,
                                             GdaCommand *cmd,
                                             GDA_CursorType cursor_type,
                                             GDA_LockType lock_type,
                                             gulong options);

This function opens a recordset. The recordset is filled with the output of cmd. Before this function is called various parameters of the recordst might be changed. This is the most featurefull function for retrieving results from a database.

rs :

the recordset

cmd :

the command object

cursor_type :

the type of the cursor used. Currently only a forward only cursor is implemented

lock_type :

the type of locks used for the command. Currently only readonly type of locking is supported.

options :

currently not implemented. Used to identify how to parse the txt.

Returns :

0 if everytrhing is okay, -1 on error


gda_recordset_open_txt ()

gint        gda_recordset_open_txt          (GdaRecordset *rs,
                                             gchar *txt,
                                             GDA_CursorType cursor_type,
                                             GDA_LockType lock_type,
                                             gulong options);

This function opens a recordset. The recordset is filled with the output of txt. Before this function is called various parameters of the recordst might be changed. This is the most featurefull function for retrieving results from a database.

rs :

the recordset

txt :

the command text

cursor_type :

the type of the cursor used. Currently only a forward only cursor is implemented

lock_type :

the type of locks used for the command. Currently only readonly type of locking is supported.

options :

currently not implemented. Used to identify how to parse the txt.

Returns :

0 if everytrhing is okay, -1 on error


gda_recordset_set_connection ()

gint        gda_recordset_set_connection    (GdaRecordset *rs,
                                             GdaConnection *cnc);

Associates a recordset with a connection. This function must not be called on a already opened recordst. This function must be called before any of the the gda_recordset_open_txt() or gda_recordset_open_cmd() functions is called.

rs :

the recordset

cnc :

the conneciton

Returns :

0 if everyhting is okay, -1 on error


gda_recordset_get_connection ()

GdaConnection* gda_recordset_get_connection (GdaRecordset *rs);

rs :

the rcordset

Returns :

the connection object used with this recordset. NULL if the recordset isn't open or there's no connection assoctiated with this recordset.


gda_recordset_add_field ()

gint        gda_recordset_add_field         (GdaRecordset *rs,
                                             GdaField *field);

rs :

field :

Returns :


gda_recordset_create ()

gint        gda_recordset_create            (GdaRecordset *rs);

rs :

Returns :


gda_recordset_get_cursorloc ()

GDA_CursorLocation gda_recordset_get_cursorloc
                                            (GdaRecordset *rs);

rs :

the recordset

Returns :

the current value of the cursor location attribute


gda_recordset_set_cursorloc ()

void        gda_recordset_set_cursorloc     (GdaRecordset *rs,
                                             GDA_CursorLocation loc);

Set the cursor location attribute to loc.

rs :

the recordset

loc :

the cursor location


gda_recordset_get_cursortype ()

GDA_CursorType gda_recordset_get_cursortype (GdaRecordset *rs);

rs :

the recordset

Returns :

the current value of the cursor type attriburte


gda_recordset_set_cursortype ()

void        gda_recordset_set_cursortype    (GdaRecordset *rs,
                                             GDA_CursorType type);

Set the cursor type attribute to type.

rs :

the recordset

type :

the cursor type