Exampls

Author: revk

sqllib.md

@@ -79,6 +79,10 @@ The format is:-
 - Optional `_store` or `_use` for queries that return rows
 - Optional suffix `_f` (for format inline), `_free` for use and free malloc'd query, `_s` for use `sql_s_t*` composed string, otherwise a query string is passed and not freed.
 
+The simplest, `sql_query(&sql,query)`,` does the query, does not free the query, does not expect a result, and returns an `int` with 0 if it worked else and error. In practice this is rarely what you want.
+
+A more complex one like `sql_safe_query_store_f(&sql,"whatever",a,b,c)` will format a query with variables, use that to do the query, free the formatted query, store teh result of the query, abort on error or return the result row set.
+
 A query like `SELECT` or `DESCRIBE` returns a value, and so you have to use a `_store` or `_use` query functions, which return `SQL_RES*`. The `_use` version streams the result from the SQL server, and is not usually what you want. Only use `_use` if you have some stupidly big query result that won't fit in memory. The `_store` versions stores the result - this has the advantage you can see how many rows there are `sql_num_rows(res)` and it completes the `SQL` query connection to allow other queries even when working through the rows of the result. You free the result with `sql_free_result(res)`. The `_safe` version always returns an `SQL_RES*` or errors, the non `_safe` returns NULL if error.
 
 A query like `UPDATE` or `INSERT` does not return a result, though `sql_insert_id(&sql)` is useful after inserts with auto incrementing IDs. These functions do not have `_use` or `_store` and have no return value (so `void` for `_safe`) or an `int` return if not `_safe` version so you know if an error (non zero return).