Transformer SDK For C  8.0.2.290852-a608fcd3
persistence_interface Struct Reference

Persistence execution functions. More...

Data Fields

int patch
 
int(* persist_call )(const char *procedure, const char *const *args, size_t args_count, kv_pair_arr *output_params)
 
int(* persist_get )(const char *table, const query_params *params, persistence_query_cb row_cb, void *row_cb_ctx)
 
int(* persist_query )(const char *table, const char *query, const query_params *params, persistence_query_cb row_cb, void *row_cb_ctx)
 
int(* persist_remove )(const char *table, const kv_pair_arr *selector)
 
int(* persist_upsert )(const char *table, const kv_pair_arr *keys, const kv_pair_arr *data)
 
int version
 

Detailed Description

Persistence execution functions.

Modules that require the persistence module, should call the appropriate function pointer in the persistence_interface structure

This interface can be obtained by calling tf_find_function("persistence_get_interface")

Field Documentation

int persistence_interface::patch

Patch version of the persistence module

int(* persistence_interface::persist_call) (const char *procedure, const char *const *args, size_t args_count, kv_pair_arr *output_params)

Function called to call a stored procedure.

Parameters
procedureprocedure to call
argsordered array of input arguments to be passed to be provided as input parameters to the procedure call.
args_countnumber of arguments
output_paramsarray of key-value pairs containing the output parameters names and their respective values. Keys are always uppercase for DBMS independence.
Return values
-1on error
Returns
1 on success

This function calls a stored procedure and returns any output parameters as key-value pairs from the parameter name to its string value. The input arguments provided are added as input parameters to the procedure call in the order they are provided.

Keys in the map passed to the callback are always uppercase for DMBS independence.

int(* persistence_interface::persist_get) (const char *table, const query_params *params, persistence_query_cb row_cb, void *row_cb_ctx)

Function called to query a specific database table for matching rows. This is a convenience wrapper around persist_query

Parameters
tabletable to retrieve data from
paramspointer to query_params to provide arguments to be bound, ordering criteria and a limit to be used with this query
row_cbfunction to be called for the first row returned by the query
row_cb_ctxcontext to be passed to the callback function
Return values
-1on error
Returns
Otherwise the number of rows returned by the query

This function executes a query against a database table and returns the rows returned in the result set. The key-value pairs in query_params::selector are built into a where clause where every key-value pair represents column-value combinations in the database table and are used in conjunction. A resulting SQL query for a selector { { "a", "10" }, { "b", "20 } } would look like select * from table where a = 10 and b = 20

In case ordering is not NULL, an ordering map of the form { { "a", "ASC" }, { "b", "DESC" } } would result in a sql order by statement like "order by a ASC, b, DESC". The order by clause will be omitted if ordering is NULL.

int(* persistence_interface::persist_query) (const char *table, const char *query, const query_params *params, persistence_query_cb row_cb, void *row_cb_ctx)

Function called to query a specific database table for matching rows

Parameters
tabletable to be queried
querysql where clause in the format "a=? or b>?" or null for all rows
paramspointer to query_params to provide arguments to be bound, ordering criteria and a limit to be used with this query
row_cbfunction to be called for every row return by the query
row_cb_ctxcontext to be passed to the callback function
Return values
-1on error
Returns
Otherwise the number of affected rows.

This function executes a query against a database and calls row_cb for every row returned by the query. If this function is called with a query like "a=? and b<?" and query_params::selector like [ { "a", "foo" }, { "b", "20} ] then the resulting sql query would look like: select * from <table> where a="foo" and b<20

In case ordering is not NULL, an ordering map of the form { { "a", "ASC" }, { "b", "DESC" } } would result in a sql order by statement like "order by a ASC, b, DESC". The order by clause will be omitted if ordering is NULL.

Note
For queries, the supplied field name in query_params::selector is ignored
int(* persistence_interface::persist_remove) (const char *table, const kv_pair_arr *selector)

Function called to remove one or more rows from a database table

Parameters
tabletable to delete rows from
selectorarray of key-value pairs to restrict the rows to be deleted.
Return values
-1on error
Returns
Otherwise the number of affected rows.

This function attempts to delete rows where all columns specified as keys in selector match the values in selector. A call to this function with a map like { {"firstname", "bob"}, {"lastname", "bar"} } would result in a sql query similar to delete from table table where firstname = bob and lastname = bar;

int(* persistence_interface::persist_upsert) (const char *table, const kv_pair_arr *keys, const kv_pair_arr *data)

Function called to update or insert data into a specific table in the database

Parameters
tabletable update or insert should be executed against
keysarray of key-value pairs to be used in the where clause for the update
dataarray of key-value pairs that should be put
Return values
-1on error
Returns
Otherwise the number of affected rows.

This function attempts to update rows where all key-value pairs given in keys match column/value pairs in the database. If this operation results in 0 affected rows, then a merged version of keys and data is inserted into the table. If keys and data share columns then the value of the data map will be taken and the value of keys is ignored. Semantically this function executes an update statement like : update {table} set data[x].field = data[x].value where key[x].field = key[x].value and if this update statement affected 0 rows, then followed by an insert like: insert into {table} (data[x].field, key[x].field) values ( data[x].value, key[x].value )

int persistence_interface::version

Version number of the persistence module


The documentation for this struct was generated from the following file:

Generated on Wed Jul 31 2024 18:00:14 for Transformer SDK For C