Database Queries
[Estron support library]

---

Detailed Description

Handler for database queries. DuiFields are used to construct an SQL query, and then run that query. Running the query returns a set of records. The resulting records can be pumpted into a different set of fields by using the DuiTxnReport structures.

Typedefs
typedef struct DuiTxnQuery_s	DuiTxnQuery
Functions
DuiTxnQuery *	dui_txnquery_new (void)
void	dui_txnquery_destroy (DuiTxnQuery *q)
void	dui_txnquery_set_table (DuiTxnQuery *qry, DuiField *tabfld, const char *sql_querytype)
void	dui_txnquery_set_tablename (DuiTxnQuery *qry, const char *tablename)
void	dui_txnquery_set_querytype (DuiTxnQuery *qry, const char *sql_querytype)
void	dui_txnquery_add_term (DuiTxnQuery *qry, DuiFieldMap *fm)
void	dui_txnquery_add_source_match_term (DuiTxnQuery *qry, DuiFieldMap *fm)
DuiFieldMap *	dui_txnquery_get_source_match_term (DuiTxnQuery *qry)
void	dui_txnquery_set_resolver (DuiTxnQuery *qry, DuiResolver *)
void	dui_txnquery_set_database (DuiTxnQuery *q, DuiDatabase *db)
void	dui_txnquery_do_realize (DuiTxnQuery *qry)
void	dui_txnquery_connect (DuiTxnQuery *qry)
DuiDBRecordSet *	dui_txnquery_run (DuiTxnQuery *qry)
DuiDBRecordSet *	dui_txnquery_rerun_last_query (DuiTxnQuery *qry)

---

Function Documentation

void dui_txnquery_add_source_match_term	(	DuiTxnQuery *	qry,
		DuiFieldMap *	fm
	)

For when the value sources are coming from a table, this specifies the way in which the source table row is matched.

The memory management for the fieldmap passed in is taken over by this routine, and when the query is deleted, the fieldmap will be too.

Definition at line 285 of file duitxnquery.c.

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

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

    qry->source_match = fm;
}

void dui_txnquery_add_term	(	DuiTxnQuery *	qry,
		DuiFieldMap *	fm
	)

Add a term to the SQL query. For SELECT field names, set the fieldmap target to DUI_FIELD_CONST. For UPDATE field & new value, set the fieldmap target to DUI_FIELD_SQL. For WHERE macthing terms, set the fieldmap target to DUI_FIELD_WHERE.

The memory management for the fieldmap passed in is taken over by this routine, and when the query is deleted, the fieldmap will be too.

< Field with const value

Definition at line 264 of file duitxnquery.c.

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

    /* If its a SELECT term then we can handle it statically.
     * The name of the SELECT field will be stored as a const target
     */
    if (DUI_FIELD_IS_TYPE(&fm->target,DUI_FIELD_CONST))
    {
        sql_builder_set_str (qry->sql_builder, fm->target.u.value, NULL);
    }
    else
    {
        qry->terms = g_list_append (qry->terms, fm);
    }
}

void dui_txnquery_connect

(

DuiTxnQuery *

qry

)

Establish connection to the SQL db. XXX this should probably be done automatically, at query-run time. We don't/shouldn't need a separate step here, right?

Definition at line 347 of file duitxnquery.c.

{
    if (!qry) return;
    qry->db_conn = dui_database_do_realize (qry->database);
}

void dui_txnquery_do_realize

(

DuiTxnQuery *

qry

)

the txnquery_do_realize is currently a no-op. and should stay that way. XXX remove this routine ... right? ...

Definition at line 336 of file duitxnquery.c.

{
    /* Everything was resolved at the time the terms were added.
     * And that's good, there's no benefit, just complications
     * and dependency-on-order-of-resolution problems with late resolution.
     */
}

void dui_txnquery_set_querytype	(	DuiTxnQuery *	qry,
		const char *	sql_querytype
	)

Specify the sql query to be performed. sql_querytype must be one of "select", "update", "insert", "delete", "tables" or "fields". The first four correspiond to the standard SQL query types. The "fields" query type can be used to obtain the column names of a given table. Handy if you don't yet know the column names. The "tables" query type can be used to obtain a listing of all the table names in the database.

void dui_txnquery_set_table	(	DuiTxnQuery *	qry,
		DuiField *	tabfld,
		const char *	sql_querytype
	)

Specify the sql table that will be queried. sql_querytype must be one of "select", "update", "insert", "delete", "tables" or "fields". If the querytype is "tables", then the 'tabfld' may be NULL; in all other cases, the 'tabfld', when evaluated, must return the name of a valid SQL table.

void dui_txnquery_set_tablename	(	DuiTxnQuery *	qry,
		const char *	tablename
	)

Specify the table name, or names, to be queried. If multiple table names are specified, they must be comma-separated (as they would normally be in an SQL statement).