Transformer Persistence API

Data Structures
struct	kv_ord
	structure holding name-persist_ordering pairs to specify ordering criteria per column and use in queries More...
struct	kv_pair
	structure holding name-value pairs for use in query_params and kv_pair_arr More...
struct	kv_pair_arr
	Represents an ordered map of columns and their values. More...
struct	persistence_interface
	Persistence execution functions. More...
struct	query_params
	struct to hold arguments for queryies More...

Typedefs
typedef int(*	filedb_init_function) (void *ctx, register_procedure_cb register_procedure_cb)
	FileDB library initialisation functionFunction to be added to FileDB stored procedure libraries to register stored procedures. More...
typedef int(*	filedb_library_function) (void *ctx, const char *const *args, const size_t args_count, kv_pair_arr *output_params)
	FileDB library procedure functionFunction to be registered as a FileDB stored procedure. More...
typedef void(*	persistence_query_cb) (void *context, const kv_pair_arr *row)
	Persistence query callback typeFor every entry returned by a persistence query a function of this type gets called to handle the received data. More...
typedef void(*	register_procedure_cb) (char *function_name, filedb_library_function function)
	Register FileDB stored procedure callbackCallback to register stored procedure functions for FileDB. More...

Enumerations

Detailed Description

About the Persistence API

This API allows C/C++ Transformer modules to interface with the Caplin PersistenceService. This service allows Transformer to connect to either a local SQLite3 Database for development purposes or to any other database via a JDBC layer. Details about how to configure this module can be found on the Caplin website and the main Transformer SDK doc.

Notes:

• The default JDBC implementation uses ResultSetMetadata which is not implemented in all versions of the jdbc driver, please refer to the documentation of the driver of your choice for more details.
• If the default JDBC bridge does not satisfy all requirements then a custom implementation can be loaded into transformer by implementing the Persistor interface described in the online documentation Persistor.java
• Table and column names are not quoted and will hence be converted to whichever case the DBMS uses. The callbacks to get and query always get called with the column names converted to uppercase to help write DMBS independent code. Because of this behaviour it is recommended to use uppercase table and column names throughout the code

Example Snippets

The following section shows examples of how to retrieve and use the module from other C/C++ transformer modules. For information on how to use the module from LUA, JS or Java please refer to the Documentation of those modules.

Modules written in C or C++

Retrieving the persistence interface

This code snippet illustrates how to retrieve the persistence_interface from transformer which can then be used to call functions on

if ( ( get_persist = tf_find_function("persistence_get_interface") ) != NULL ) {
    persistence = get_persist();
}

Upsert (update or insert) data in a table of your choice

This snippet shows how to use persistence_interface::persist_upsert.

kv_pair keys_arr[] = { { "ID", "1" } };
kv_pair pairs[] = {
    { "ID",     "1"},
    { "NAME",   "Adam"}
};
kv_pair_arr keys = { .count = 1, .pairs = keys_arr};
kv_pair_arr data = { .count = 2, .pairs = pairs };

int ret = persistence->upsert("MY_TABLE", &keys, &data);

Deletion of rows

This snippet shows how to use persistence_interface::persist_remove.

kv_pair keys_arr[] = { { "ID", "1" } };
kv_pair_arr selector = { .count = 1, .pairs = keys_arr};
ret = persistence->remove("MY_TABLE", &selector);

Retrieving data - Query

This snippet shows how to use persistence_interface::persist_query.

void row_cb(void *context, const kv_pair_arr *row) {
    //do something with the row data
}

// *************

kv_pair pairs[] = {
    { "id", "5" },
    { "id", "10" }
};
query_params params = { .selector_count = 2, .selector = pairs, .order_count = 0, .ordering = NULL, .limit = 0 };

ret = persistence->query("MY_TABLE", NULL, NULL, row_cb, NULL);

Retrieving data - Get

This snippet shows how to use persistence_interface::persist_get.

void row_cb(void *context, const kv_pair_arr *row) {
    //do something with the row data
}

// *************

kv_pair pairs[] = {
    { "FIRSTNAME", "Adam" },
    { "LASTNAME",  "Bdam" }
};
query_params params = { .selector_count = 2, .selector = pairs, .order_count = 0, .ordering = NULL, .limit = 0 };

ret = persistence->get("MY_TABLE", &params, test_cb, &data);

Typedef Documentation

typedef int(* filedb_init_function) (void *ctx, register_procedure_cb register_procedure_cb)

FileDB library initialisation functionFunction to be added to FileDB stored procedure libraries to register stored procedures.

typedef int(* filedb_library_function) (void *ctx, const char *const *args, const size_t args_count, kv_pair_arr *output_params)

FileDB library procedure functionFunction to be registered as a FileDB stored procedure.

typedef void(* persistence_query_cb) (void *context, const kv_pair_arr *row)

Persistence query callback typeFor every entry returned by a persistence query a function of this type gets called to handle the received data.

typedef void(* register_procedure_cb) (char *function_name, filedb_library_function function)

Register FileDB stored procedure callbackCallback to register stored procedure functions for FileDB.

Enumeration Type Documentation

enum persist_ordering

enum defining sort order