QOF  0.8.7
Typedefs | Enumerations | Functions

Typedefs

typedef struct _QofSqlQuery QofSqlQuery
 

Enumerations

enum  QsqlStatementType {
  SQL_NONE = 0, SQL_CREATE, SQL_LOAD, SQL_WRITE,
  SQL_INSERT, SQL_DELETE, SQL_UPDATE
}
 

Functions

void qof_sql_entity_set_kvp_tablename (const gchar *name)
 Set a default KVP table name for each backend. More...
 
void qof_sql_entity_set_kvp_id (gulong id)
 Set the initial index value of the KVP table. More...
 
gulong qof_sql_entity_get_kvp_id (void)
 Get the index value of the KVP table after the operation(s). More...
 
void qof_sql_entity_set_kvp_exists (gboolean exist)
 Set or clear a flag that the KVP table exists or not. More...
 
gchar * qof_sql_entity_create_table (QofEntity *ent)
 Build a SQL 'CREATE' statement for this entity. More...
 
gchar * qof_sql_entity_insert (QofEntity *ent)
 Build a SQL 'INSERT' statement for this entity. More...
 
gchar * qof_sql_entity_update (QofEntity *ent)
 Build a SQL 'UPDATE' statement for the current entity parameter. More...
 
gchar * qof_sql_entity_update_kvp (QofEntity *ent)
 Build a SQL 'UPDATE' statement for the KVP data in this entity. More...
 
gchar * qof_sql_entity_update_list (QofEntity *ent, GList **params)
 Build a SQL 'UPDATE' statement for a list of parameters. More...
 
gchar * qof_sql_entity_delete (QofEntity *ent)
 Build a SQL 'DELETE' statement for this entity. More...
 
gchar * qof_sql_entity_drop_table (QofEntity *ent)
 Build a SQL 'DROP' statement for this entity type. More...
 
gchar * qof_sql_object_create_table (QofObject *obj)
 Build a SQL 'CREATE' statement for this object. More...
 
QofSqlQuery * qof_sql_query_new (void)
 
void qof_sql_query_destroy (QofSqlQuery *)
 
void qof_sql_query_set_book (QofSqlQuery *q, QofBook *book)
 
GList * qof_sql_query_run (QofSqlQuery *query, const gchar *str)
 Perform the query, return the results. More...
 
void qof_sql_query_parse (QofSqlQuery *query, const gchar *str)
 
QofQueryqof_sql_query_get_query (QofSqlQuery *)
 
GList * qof_sql_query_rerun (QofSqlQuery *query)
 
void qof_sql_query_set_kvp (QofSqlQuery *, KvpFrame *)
 

Detailed Description

The qof_sql_entity* functions are private - only accessible to QOF backends. The purpose is to make it easier for SQL-based backends to pass SQL commands to the relevant database. There is currently no QOF support for reading the entities back from the backend as each backend has specialized methods for data retrieval (GDA has GdaDataModel, sqlite uses **columnNames etc.) Actually, it is generally easier to read data from a SQL based backend than it is to create, update or delete data.

Note
qof_sql_entity_update relies on qof_util_param_edit and qof_util_param_commit which identify the particular parameter to be committed.

The types of SQL queries that are allowed at this point are very limited. In general, only the following types of queries are supported: SELECT * FROM SomeObj WHERE (param_a < 10.0) AND (param_b = "asdf") SORT BY param_c DESC; INSERT INTO SomeObj (param_a, param_b, param_c) VALUES ("value_a", true, "0/1");

For SELECT, the returned list is a list of all of the instances of 'SomeObj' that match the query. The 'SORT' term is optional. The 'WHERE' term is optional; but if you don't include 'WHERE', you will get a list of all of the object instances. The Boolean operations 'AND' and 'OR' together with parenthesis can be used to construct arbitrarily nested predicates.

For INSERT, the returned list is a list containing the newly created instance of 'SomeObj'.

Joins are not supported directly. SELECT * FROM ObjA,ObjB WHERE (ObjA.param_id = ObjB.param_other_id); The problem with the above is that the search requires a nested search loop, aka a 'join', which is not currently supported in the underlying QofQuery code.

However, by repeating queries and adding the entities to a new session using qof_entity_copy_list, a series of queries can be added to a single book. e.g. You can insert multiple entities and save out as a QSF XML file or use multiple SELECT queries to build a precise list - this can be used to replicate most of the functionality of a SQL join.

SELECT * from ObjA where param_id = value; SELECT * from ObjB where param_other_id = value;

Equivalent to: SELECT * from ObjA,ObjB where param_id = param_other_id and param_id = value;

When combined with a foreach callback on the value of param_id for each entity in the QofBook, you can produce the effect of a join from running the two SELECT queries for each value of param_id held in 'value'.

See QofEntityForeachCB and qof_object_foreach.

Date queries handle full date and time strings, using the format exported by the QSF backend. To query dates and times, convert user input into UTC time using the QOF_UTC_DATE_FORMAT string. See qof_date_print

If the param is a KVP frame, then we use a special markup to indicate frame values. The markup should look like /some/kvp/path:value. Thus, for example, SELECT * FROM SomeObj WHERE (param_a < '/some/kvp:10.0') will search for the object where param_a is a KVP frame, and this KVP frame contains a path '/some/kvp' and the value stored at that path is floating-point and that float value is less than 10.0.

The following are types of queries are NOT supported: SELECT a,b,c FROM ... I am thinking of implementing the above as a list of KVP's whose keys would be a,b,c and values would be the results of the search. (Linas)

XXX (Neil W). Alternatively, I need to use something like this when converting QOF objects between applications by using the returned parameter values to create a second object. One application using QOF could register objects from two applications and convert data from one to the other by using SELECT a,b,c FROM ObjA; SELECT d,f,k FROM ObjB; qof_object_new_instance(); ObjC_set_a(value_c); ObjC_set_b(value_k) etc. What's needed is for the SELECT to return a complete object that only contains the parameters selected.

Also unsupported: UPDATE.

Certain SQL commands can have no QOF equivalent and will generate a runtime parser error:

Enumeration Type Documentation

Enumerator
SQL_NONE 

no operation defined. init value.

SQL_CREATE 

Create a new database

SQL_LOAD 

Load all data from existing database.

SQL_WRITE 

Write / sync all data to the database.

SQL_INSERT 

Run a single INSERT statement.

SQL_DELETE 

Run a single DELETE statement.

SQL_UPDATE 

Run a single UPDATE statement.

Definition at line 54 of file qofsql-p.h.

55 {
57  SQL_NONE = 0,
59  SQL_CREATE,
61  SQL_LOAD,
63  SQL_WRITE,
65  SQL_INSERT,
67  SQL_DELETE,
QsqlStatementType
Definition: qofsql-p.h:54

Function Documentation

gchar* qof_sql_entity_create_table ( QofEntity ent)

Build a SQL 'CREATE' statement for this entity.

Prepares a SQL statement that will create a table for this entity.

Definition at line 1368 of file qofsql.c.

1369 {
1370  gchar * sql_str, * start;
1371  eas data;
1372 
1373  g_return_val_if_fail (ent, NULL);
1374  if (!kvp_table_name)
1375  kvp_table_name = g_strdup(QSQL_KVP_TABLE);
1376  ENTER ("create table for %s", ent->e_type);
1377  start = g_strdup_printf ("CREATE TABLE %s (", ent->e_type);
1378  data.ent = ent;
1379  data.str = g_strdup("");
1380  data.kvp_str = g_strdup("");
1381  qof_class_param_foreach (ent->e_type, string_param_foreach, &data);
1382  sql_str = g_strjoin ("", start, data.str, END_DB_VERSION, data.kvp_str, NULL);
1383  g_free (start);
1384  LEAVE ("sql_str=%s", sql_str);
1385  return sql_str;
1386 }
#define QSQL_KVP_TABLE
Definition: qof-sqlite.c:55
void qof_class_param_foreach(QofIdTypeConst obj_name, QofParamForeachCB cb, gpointer user_data)
Definition: qofclass.c:268
#define LEAVE(format, args...)
Definition: qoflog.h:227
static gchar * kvp_table_name
Definition: qofsql.c:51
struct ent_and_string eas
#define ENTER(format, args...)
Definition: qoflog.h:217
gchar* qof_sql_entity_delete ( QofEntity ent)

Build a SQL 'DELETE' statement for this entity.

Prepares a SQL statement that will delete the row for this entity into the appropriate table (which must already exist). The data for the entity must already have been INSERTed into the table.

Also deletes all KVP data for this entity.

Definition at line 1535 of file qofsql.c.

1536 {
1537  gchar * gstr, * sql_str;
1538  ENTER (" %s", ent->e_type);
1539  gstr = g_strnfill (GUID_ENCODING_LENGTH + 1, ' ');
1541  sql_str = g_strconcat ("DELETE from ", ent->e_type, " WHERE ",
1542  QOF_TYPE_GUID, "='", gstr, "';", "DELETE from ", kvp_table_name,
1543  " WHERE kvp_id ", "='", gstr, "';", NULL);
1544  g_free (gstr);
1545  return sql_str;
1546 }
#define GUID_ENCODING_LENGTH
Definition: guid.h:64
static gchar * kvp_table_name
Definition: qofsql.c:51
gchar * guid_to_string_buff(const GUID *guid, gchar *buff)
const GUID * qof_entity_get_guid(QofEntity *ent)
Definition: qofid.c:105
#define ENTER(format, args...)
Definition: qoflog.h:217
gchar* qof_sql_entity_drop_table ( QofEntity ent)

Build a SQL 'DROP' statement for this entity type.

Prepares a SQL statement that will DROP the table for this entity type. (This function is fairly obvious but exists for completeness.) The table must already exist.

Definition at line 1549 of file qofsql.c.

1550 {
1551  gchar * sql_str;
1552  ENTER (" drop table for '%s'", ent->e_type);
1553  sql_str = g_strdup_printf ("DROP TABLE %s;", ent->e_type);
1554  LEAVE ("sql_str=%s", sql_str);
1555  return sql_str;
1556 }
#define LEAVE(format, args...)
Definition: qoflog.h:227
#define ENTER(format, args...)
Definition: qoflog.h:217
gulong qof_sql_entity_get_kvp_id ( void  )

Get the index value of the KVP table after the operation(s).

Each backend table has an ID number for KVP entries as one QofEntity can have multiple KvpFrames. The ID number is mapped to the GUID of the entity when reading data back from the table.

The ID is incremented after each call to qof_sql_entity_insert where qof_instance_get_slots does not return an empty frame.

Definition at line 1569 of file qofsql.c.

1570 {
1571  return kvp_id;
1572 }
gchar* qof_sql_entity_insert ( QofEntity ent)

Build a SQL 'INSERT' statement for this entity.

Prepares a SQL statement that will insert data for this entity into the appropriate table (which must already exist).

Definition at line 1389 of file qofsql.c.

1390 {
1391  KvpFrame * slots;
1392  eas data;
1393  gchar * command, * fields, * values, *id, *gstr, *sql_str, *kvp;
1394 
1395  data.ent = ent;
1396  data.str = g_strdup("");
1397  if (!kvp_table_name)
1398  kvp_table_name = g_strdup(QSQL_KVP_TABLE);
1399  ENTER (" insert a single '%s'", ent->e_type);
1400  gstr = g_strnfill (GUID_ENCODING_LENGTH + 1, ' ');
1402  DEBUG (" guid=%s", gstr);
1403  command = g_strdup_printf ("INSERT into %s (guid ", ent->e_type);
1404  // store param list in fields
1405  qof_class_param_foreach (ent->e_type, create_param_list, &data);
1406  fields = g_strdup(data.str);
1407  // store param values in values
1408  g_free (data.str);
1409  data.str = g_strdup("");
1410  data.full_kvp_path = g_strdup("");
1411  qof_class_param_foreach (ent->e_type, create_sql_from_param_cb, &data);
1412  values = data.str;
1413  /* handle KVP */
1414  kvp = g_strdup("");
1415  slots = qof_instance_get_slots ((QofInstance *) ent);
1416  if (!kvp_frame_is_empty(slots))
1417  {
1418  id = g_strdup_printf ("%lu", kvp_id);
1419  g_free (kvp);
1421  kvp = g_strconcat (" INSERT into ", kvp_table_name,
1422  " (kvp_id, guid, type, path, value) VALUES ('", id, "', '",
1423  gstr, "', ", data.str, ");", NULL);
1424  /* increment the index value of the KVP table */
1425  kvp_id++;
1426  g_free (data.str);
1427  }
1428  sql_str = g_strjoin ("", command, fields, ") VALUES ('", gstr, "' ",
1429  values, ");", kvp, NULL);
1430  g_free (command);
1431  g_free (fields);
1432  g_free (gstr);
1433  g_free (values);
1434  g_free (data.full_kvp_path);
1435  LEAVE ("sql_str=%s", sql_str);
1436  return sql_str;
1437 }
#define QSQL_KVP_TABLE
Definition: qof-sqlite.c:55
void qof_class_param_foreach(QofIdTypeConst obj_name, QofParamForeachCB cb, gpointer user_data)
Definition: qofclass.c:268
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
gboolean kvp_frame_is_empty(KvpFrame *frame)
Definition: kvpframe.c:134
#define LEAVE(format, args...)
Definition: qoflog.h:227
#define GUID_ENCODING_LENGTH
Definition: guid.h:64
const GUID * qof_instance_get_guid(QofInstance *inst)
Definition: qofinstance.c:79
KvpFrame * qof_instance_get_slots(QofInstance *inst)
Definition: qofinstance.c:95
static gchar * kvp_table_name
Definition: qofsql.c:51
#define DEBUG(format, args...)
Definition: qoflog.h:208
static void create_param_list(QofParam *param, gpointer user_data)
list just the parameter names
Definition: qofsql.c:1220
gchar * guid_to_string_buff(const GUID *guid, gchar *buff)
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB proc, gpointer data)
Definition: kvpframe.c:1642
struct ent_and_string eas
#define ENTER(format, args...)
Definition: qoflog.h:217
static void kvpvalue_to_sql_insert(const gchar *key, KvpValue *val, gpointer user_data)
Definition: qofsql.c:1252
void qof_sql_entity_set_kvp_exists ( gboolean  exist)

Set or clear a flag that the KVP table exists or not.

The KVP table should only be created once per session - use this flag to indicate that the KVP table has been successfully created (or deleted).

qof_sql_entity_create_table will not attempt to create the KVP table if this flag is set. It is up to the backend to control this flag.

Definition at line 1574 of file qofsql.c.

1575 {
1576  kvp_table_exists = exist;
1577 }
void qof_sql_entity_set_kvp_id ( gulong  id)

Set the initial index value of the KVP table.

Each backend table has an ID number for KVP entries as one QofEntity can have multiple KvpFrames. The ID number is mapped to the GUID of the entity when reading data back from the table.

The ID is incremented after each call to qof_sql_entity_insert where qof_instance_get_slots does not return an empty frame.

Definition at line 1564 of file qofsql.c.

1565 {
1566  kvp_id = id;
1567 }
void qof_sql_entity_set_kvp_tablename ( const gchar *  name)

Set a default KVP table name for each backend.

Each backend can choose a different KVP table name by overwriting the default name (sql_kvp) with this function.

e.g. the SQLite backend uses 'sqlite_kvp'.

Definition at line 1558 of file qofsql.c.

1559 {
1560  g_return_if_fail (name);
1561  kvp_table_name = g_strdup(name);
1562 }
static gchar * kvp_table_name
Definition: qofsql.c:51
gchar* qof_sql_entity_update ( QofEntity ent)

Build a SQL 'UPDATE' statement for the current entity parameter.

Prepares a SQL statement that will update a single parameter for this entity into the appropriate table (which must already exist). The data for the entity must already have been INSERTed into the table.

Definition at line 1460 of file qofsql.c.

1461 {
1462  gchar *gstr, * sql_str, * param_str;
1463  QofInstance * inst;
1464  const QofParam * param;
1465  inst = (QofInstance*)ent;
1466 
1467  if (!inst->param)
1468  return NULL;
1469  ENTER (" modified %s param:%s", ent->e_type, inst->param->param_name);
1470  gstr = g_strnfill (GUID_ENCODING_LENGTH + 1, ' ');
1472  param = inst->param;
1473  if (0 == safe_strcmp (param->param_type, QOF_TYPE_COLLECT))
1474  {
1475  gchar * name;
1476  QofCollection * coll;
1477 
1478  coll = param->param_getfcn (ent, param);
1479  name = g_strdup (param->param_name);
1480  qof_collection_foreach (coll, collect_kvp, name);
1481  g_free (name);
1482  return NULL;
1483  }
1484  param_str = qof_util_param_to_string (ent, inst->param);
1485  if (param_str)
1486  g_strescape (param_str, NULL);
1487  sql_str = g_strconcat ("UPDATE ", ent->e_type, " SET ",
1488  inst->param->param_name, " = '", param_str,
1489  "' WHERE ", QOF_TYPE_GUID, "='", gstr, "';", NULL);
1490  LEAVE ("sql_str=%s", sql_str);
1491  return sql_str;
1492 }
#define QOF_TYPE_COLLECT
secondary collections are used for one-to-many references between entities and are implemented using ...
Definition: qofclass.h:121
#define LEAVE(format, args...)
Definition: qoflog.h:227
#define GUID_ENCODING_LENGTH
Definition: guid.h:64
struct QofCollection_s QofCollection
Definition: qofid.h:138
const GUID * qof_instance_get_guid(QofInstance *inst)
Definition: qofinstance.c:79
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
Definition: qofid.c:392
gchar * qof_util_param_to_string(QofEntity *ent, const QofParam *param)
Converts a parameter to a string for storage or display.
Definition: qofutil.c:464
gchar * guid_to_string_buff(const GUID *guid, gchar *buff)
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:75
const QofParam * param
Definition: qofinstance-p.h:53
#define ENTER(format, args...)
Definition: qoflog.h:217
gchar* qof_sql_entity_update_kvp ( QofEntity ent)

Build a SQL 'UPDATE' statement for the KVP data in this entity.

Prepares a SQL statement that will update the KVP data for this entity (if any) into the KVP table.

This is a separate function because the KVP data can be modified independently of other parameters and updating a parameter should not cause an unwanted SQL operation on unchanged KVP data. If you know that the KVP data has changed, concatenate the two SQL commands into one.

Note
the WHERE condition tests the path and the GUID as each entity (one GUID) can have more than one KVP.

Definition at line 1495 of file qofsql.c.

1496 {
1497  eas data;
1498  gchar *gstr, * sql_str;
1499  QofInstance * inst;
1500  gchar * start;
1501  KvpFrame * slots;
1502  inst = (QofInstance*)ent;
1503 
1504  if (!inst->param)
1505  return NULL;
1506  sql_str = NULL;
1508  return NULL;
1509 
1510  ENTER (" modified %s param:%s", ent->e_type, inst->param->param_name);
1511  gstr = g_strnfill (GUID_ENCODING_LENGTH + 1, ' ');
1513  data.str = g_strdup("");
1514  data.full_kvp_path = g_strdup("");
1515  slots = qof_instance_get_slots ((QofInstance*)ent);
1516  start = g_strjoin ("", "UPDATE ", kvp_table_name, " SET ", NULL);
1520  sql_str = g_strjoin ("", start, data.str, " guid='", gstr, "';", NULL);
1521  g_free (start);
1522  g_free (data.full_kvp_path);
1523  g_free (data.str);
1524  LEAVE ("sql_str=%s", sql_str);
1525  return sql_str;
1526 }
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
static void kvpvalue_to_sql_update(const gchar *key, KvpValue *val, gpointer user_data)
Definition: qofsql.c:1300
gboolean kvp_frame_is_empty(KvpFrame *frame)
Definition: kvpframe.c:134
#define LEAVE(format, args...)
Definition: qoflog.h:227
#define GUID_ENCODING_LENGTH
Definition: guid.h:64
const GUID * qof_instance_get_guid(QofInstance *inst)
Definition: qofinstance.c:79
KvpFrame * qof_instance_get_slots(QofInstance *inst)
Definition: qofinstance.c:95
static gchar * kvp_table_name
Definition: qofsql.c:51
gchar * guid_to_string_buff(const GUID *guid, gchar *buff)
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB proc, gpointer data)
Definition: kvpframe.c:1642
const QofParam * param
Definition: qofinstance-p.h:53
struct ent_and_string eas
#define ENTER(format, args...)
Definition: qoflog.h:217
gchar* qof_sql_entity_update_list ( QofEntity ent,
GList **  params 
)

Build a SQL 'UPDATE' statement for a list of parameters.

Prepares a SQL statement that will update the specified parameters for this entity into the appropriate table (which must already exist). The data for the entity must already have been INSERTed into the table.

Bug:
unfinished function.

Definition at line 1529 of file qofsql.c.

1530 {
1531  return NULL;
1532 }
gchar* qof_sql_object_create_table ( QofObject obj)

Build a SQL 'CREATE' statement for this object.

Prepares a SQL statement that will create a table for this object for those times when an entity does not yet exist.

Definition at line 1346 of file qofsql.c.

1347 {
1348  gchar * sql_str, * start;
1349  eas data;
1350 
1351  if (!kvp_table_name)
1352  kvp_table_name = g_strdup(QSQL_KVP_TABLE);
1353  ENTER ("create table for %s", obj->e_type);
1354  start = g_strdup_printf ("CREATE TABLE %s (", obj->e_type);
1355  data.ent = NULL;
1356  data.str = g_strdup("");
1357  data.kvp_str = g_strdup("");
1358  qof_class_param_foreach (obj->e_type, string_param_foreach, &data);
1359  sql_str = g_strjoin ("", start, data.str, END_DB_VERSION, data.kvp_str, NULL);
1360  g_free (start);
1361  g_free (data.kvp_str);
1362  g_free (data.str);
1363  LEAVE ("sql_str=%s", sql_str);
1364  return sql_str;
1365 }
#define QSQL_KVP_TABLE
Definition: qof-sqlite.c:55
void qof_class_param_foreach(QofIdTypeConst obj_name, QofParamForeachCB cb, gpointer user_data)
Definition: qofclass.c:268
#define LEAVE(format, args...)
Definition: qoflog.h:227
static gchar * kvp_table_name
Definition: qofsql.c:51
struct ent_and_string eas
#define ENTER(format, args...)
Definition: qoflog.h:217
QofQuery* qof_sql_query_get_query ( QofSqlQuery *  )

Return the QofQuery form of the previously parsed query.

Definition at line 103 of file qofsql.c.

104 {
105  if (!q)
106  return NULL;
107  return q->qof_query;
108 }
QofSqlQuery* qof_sql_query_new ( void  )

Create a new SQL-syntax query machine.

Definition at line 75 of file qofsql.c.

76 {
77  QofSqlQuery *sqn = (QofSqlQuery *) g_new0 (QofSqlQuery, 1);
78 
79  sqn->qof_query = NULL;
80  sqn->parse_result = NULL;
81  sqn->book = NULL;
82  sqn->single_global_tablename = NULL;
83  sqn->kvp_join = NULL;
84 
85  return sqn;
86 }
void qof_sql_query_parse ( QofSqlQuery *  query,
const gchar *  str 
)

Same qof_sql_query_run, but just parse/pre-process the query; do not actually run it over the dataset. The QofBook does not need to be set before calling this function.

GList* qof_sql_query_rerun ( QofSqlQuery *  query)

Run the previously parsed query. The QofBook must be set before this function can be called. Note, teh QofBook can be changed between each successive call to this routine. This routine can be called after either qof_sql_query_parse() or qof_sql_query_run() because both will set up the parse.

Definition at line 1044 of file qofsql.c.

1045 {
1046  GList *results;
1047 
1048  if (!query)
1049  return NULL;
1050 
1051  if (NULL == query->qof_query)
1052  return NULL;
1053 
1054  qof_query_set_book (query->qof_query, query->book);
1055 
1056  /* Maybe log this sucker */
1057  if (qof_log_check (log_module, QOF_LOG_DETAIL))
1058  {
1059  qof_query_print (query->qof_query);
1060  }
1061 
1062  results = qof_query_run (query->qof_query);
1063 
1064  return results;
1065 }
gboolean qof_log_check(QofLogModule log_module, QofLogLevel log_level)
Definition: qoflog.c:204
void qof_query_set_book(QofQuery *q, QofBook *book)
Definition: qofquery.c:1335
GList * qof_query_run(QofQuery *q)
Definition: qofquery.c:757
GList* qof_sql_query_run ( QofSqlQuery *  query,
const gchar *  str 
)

Perform the query, return the results.

The book must be set in order to be able to perform a query.

The returned list will have been sorted using the indicated sort order, (by default ascending order) and trimmed to the max_results length. Do NOT free the resulting list. This list is managed internally by QofSqlQuery.

void qof_sql_query_set_book ( QofSqlQuery *  q,
QofBook book 
)

Set the book to be searched (you can search multiple books) If no books are set, no results will be returned (since there is nothing to search over).

Definition at line 113 of file qofsql.c.

114 {
115  if (!q)
116  return;
117  q->book = book;
118 }
void qof_sql_query_set_kvp ( QofSqlQuery *  ,
KvpFrame  
)

Set the kvp frame to be used for formulating 'indirect' predicates.

Although joins are not supported (see above), there is one special hack that one can use to pass data indirectly into the predicates. This is by using a KVP key name to reference the value to be used for a predicate. Thus, for example, SELECT * FROM SomeObj WHERE (param_a = KVP:/some/key/path); will look up the value stored at '/some/key/path', and use that value to form the actual predicate. So, for example, if the value stored at '/some/key/path' was 2, then the actual query run will be SELECT * FROM SomeObj WHERE (param_a = 2); The lookup occurs at the time that the query is formulated.

The query does not take over ownership of the kvp frame, nor does it copy it. Thus, the kvp frame must exist when the query is formulated, and it is the responsibility of the caller to free it when no longer needed.

Note that because this feature is a kind of a hack put in place due to the lack of support for joins, it will probably go away (be deprecated) if/when joins are implemented.

Definition at line 123 of file qofsql.c.

124 {
125  if (!q)
126  return;
127  q->kvp_join = kvp;
128 }