Database Reports
[Estron support library]

---

Detailed Description

A 'txnreport' will fill in a bunch of field values, based on a previously obtained collection of SQL records (i.e. the results of a previous SQL query.) This is typically used to fill in fields that are in gtk widgets, and/or possibly a gtk table widget. The txnreport can handle multiple table rows in the latter case.

The set of db records should probably be obtained using DuiTxnQuery, although this is not a requirement (yet?).

Another way to think of this thing as being a grouping of fieldmaps, a 'table' as it were. Data is copied from the SQL query into this grouping as a unit.

Bug:

except that this is wrong. we have two competing concepts: the set of data that came in from sql, and the way that it will be mapped to the targets. We need a distinct concept of target tables with matchers.

but this is the matcher. We need to declare the matching terms here, not else where.

Files
file	duitxnreport.h
Typedefs
typedef struct DuiTxnReport_s	DuiTxnReport
Functions
DuiTxnReport *	dui_txnreport_new (const char *name, int nest)
void	dui_txnreport_destroy (DuiTxnReport *row)
const char *	dui_txnreport_get_name (DuiTxnReport *)
int	dui_txnreport_get_nest (DuiTxnReport *)
void	dui_txnreport_add_term (DuiTxnReport *row, DuiFieldMap *fm)
void	dui_txnreport_add_match_term (DuiTxnReport *row, DuiFieldMap *fm)
void	dui_txnreport_set_resolver (DuiTxnReport *row, DuiResolver *res)
gboolean	dui_txnreport_is_empty (DuiTxnReport *row, DuiDBRecordSet *recs)
void	dui_txnreport_run (DuiTxnReport *row, DuiDBRecordSet *recs)

---

Function Documentation

void dui_txnreport_add_match_term	(	DuiTxnReport *	row,
		DuiFieldMap *	fm
	)

Specify a 'matcher' term which must be satisfied for a row to be filled out. The matcher will typically indicate a row in a table widget, or a specific instance of an object.

Definition at line 131 of file duitxnreport.c.

{
    if (!row || !fm) return;

    if (row->match)
    {
        PERR ("Target Row Matcher already specified!\n");
    }
    dui_resolver_add_field (row->resolver, &fm->source);
    dui_resolver_add_field (row->resolver, &fm->target);
    dui_field_map_resolve (fm);

    row->match = fm;
}

void dui_txnreport_add_term	(	DuiTxnReport *	row,
		DuiFieldMap *	fm
	)

Add a 'column' to this 'row'. The fieldmap acts to specify a data target when the report is run.

Definition at line 120 of file duitxnreport.c.

{
    if (!row || !fm) return;
    dui_resolver_add_field (row->resolver, &fm->source);
    dui_resolver_add_field (row->resolver, &fm->target);
    dui_field_map_resolve (fm);

    row->columns = g_list_append (row->columns, fm);
}

gboolean dui_txnreport_is_empty	(	DuiTxnReport *	row,
		DuiDBRecordSet *	recs
	)

Return TRUE if no data transfer would result, for instance because there's no data in the recordset

Definition at line 178 of file duitxnreport.c.

{
    gint more_rows = 1;

    if (!row) return TRUE;

    /* Check to see if there's any data to display at all.  Note
     * that 'recs' may be NULL; there could still be static data
     * or non-sql data. So must go through loop at least once.
     * Note also that the empty string "" is a valid value, and
     * its used to clear out/empty target fields.
     *
     * However, if DB returned zero rows, then the DB may be offline,
     * or the query may have been badly constructed.  Should check
     * for these errors ...
     */
    dui_recordset_rewind (recs);
    while (more_rows)
    {
        GList *cnode;
        for (cnode=row->columns; cnode; cnode=cnode->next)
        {
            DuiFieldMap *col = cnode->data;
            const gchar * val;

            dui_field_resolve_recordset (&col->source, recs);
            val = dui_field_map_get_value (col);
            if (val)
            {
                PINFO ("have data rows for row=%p %s", row, row->row_name);
                return FALSE;
            }
        }

        more_rows = dui_recordset_fetch_row (recs);
    }
    PINFO ("empty row=%p %s", row, row->row_name);
    return TRUE;
}

void dui_txnreport_run	(	DuiTxnReport *	row,
		DuiDBRecordSet *	recs
	)

Force the data transer to occur

Definition at line 222 of file duitxnreport.c.

{
    gint more_rows = 1;
    DuiField *iterator = NULL;

    if (!row) return;
    ENTER ("(rowname=%s, recs=%p)", row->row_name, recs);

    /* Handle the matching term first */
    if (row->match)
    {
        iterator = &row->match->target;
    }

    dui_field_iter_pre (iterator, (0 == row->nest_level));

    /* Note, we must pass through this at least once, even
     * if there  are no rows in the recordset.  That's because
     * some fields will be static, not coming from SQL
     *
     * However, if DB returned zero rows, then the DB may be offline,
     * or the query may have been badly constructed.  Should check
     * for these errors...
     */
    dui_recordset_rewind (recs);
    more_rows = 1;
    while (more_rows)
    {
        gboolean do_transfer;
        /* Fetch the match value, if its been set */
        if (row->match)
        {
            dui_field_resolve_recordset (&row->match->source, recs);
            dui_field_map_transfer_data (row->match);
        }

        do_transfer = dui_field_iter_next (iterator);

        if (do_transfer)
        {
            GList *cnode;
            for (cnode=row->columns; cnode; cnode=cnode->next)
            {
                DuiFieldMap *col = cnode->data;

                dui_field_resolve_recordset (&col->source, recs);
                dui_field_iter_column (&col->target, iterator);

                /* OK, finally move data from source to dest */
                dui_field_map_transfer_data (col);
            }
        }

        more_rows = 0;
        if (recs) more_rows = dui_recordset_fetch_row (recs);
        PINFO ("recs=%p more_rows=%d", recs, more_rows);
    }

    dui_field_iter_post (iterator);
    LEAVE ("(rowname=%s) iterator=%p", row->row_name, iterator);
}