cprops - c prototyping tools

implementing a cp_dbms driver

man page index

doxygen documentation

code samples


implementing a cp_dbms driver

cpsvc README


SourceForge Project page

It is easy and fun to implement a driver for the cp_dbms database abstraction layer. Just use these files as templates:



cp_dbms provides functions to load drivers by name. By default driver code is not linked statically but rather loaded dynamically from a shared object. For the driver descriptor string "DATABASE" (for example) cp_dbms_load_driver attempts to load driver code from a shared object named libcp_dbms_DATABASE.so .
  • if a function named cp_dbms_DATABASE_init (replace DATABASE with driver descriptor string) is found it is invoked. The prototype for the initialization function should follow
        void cp_dbms_DATBASE_init();
    To register a shutdown call with the cp_dbms framework, use cp_db_register_dbms .

  • the driver implementation must define a function named cp_dbms_DATABASE_get_data_source. The prototype for this function should follow
        cp_data_source *
            cp_dbms_DATABASE_get_data_source(char *host, 
                                             int port, 
                                             char *login, 
                                             char *password,
                                             char *dbname);

    Optionally implementations may define a function db_dbms_DATABASE_get_data_source_prm defined as

        cp_data_source *
            cp_dbms_DATABASE_get_data_source_prm(char *host,
                                                 int port, 
                                                 char *login, 
                                                 char *password, 
                                                 char *dbname, 
                                                 cp_hashtable *prm);
    allowing passing addtional named parameters as key-value pairs in the prm hashtable.

    The cp_data_source structure is used to hold the parameters for a connection to a specific instance with specific connection parameters (user name, port, etc) and is defined as follows:

        typedef struct _cp_data_source
            cp_db_connection_parameters *prm;
            cp_db_actions               *act;
        } cp_data_source; 

    The cp_db_connection_parameters structure is a wrapper for implementation specific parameters containing a pointer to the actual parameters and a pointer to a destructor function. The cp_db_actions structure holds function pointers to methods implementing database operations. It may be instantiated with cp_db_action_create, which is defined so:

        cp_db_actions *
            cp_db_actions_create(int dbms,
                                 char *dbms_lit,
                                 cp_db_open_fn open,
                                 cp_db_select_fn select,
                                 cp_db_fetch_metadata_fn fetch_metadata,
                                 cp_db_fetch_next_fn fetch_next,
                                 cp_db_release_result_set_fn release_result_set,
                                 cp_db_update_fn update,
                                 cp_db_close_fn close,
                                 cp_db_escape_string_fn escape_string,
                                 cp_db_escape_binary_fn escape_binary,
                                 cp_db_unescape_binary_fn unescape_binary,
                                 cp_db_prepare_statement_fn prepare_statement,
                                 cp_db_execute_statement_fn execute_statement,
                                 cp_db_release_statement_fn release_statement,
                                 cp_db_set_autocommit_fn set_autocommit,
                                 cp_db_commit_fn commit,
                                 cp_db_rollback_fn rollback);
    Driver implementations are required as a minimum to implement the following methods:
    1. a function to open new connections, defined as
      cp_db_connection *open_connection(cp_data_source *data_source);
    2. a function to perform queries returning result sets, eg SELECT:
      cp_result_set *perform_select(cp_db_connection *_conn, char *query);
    3. a function to perform update queries, eg UPDATE, INSERT etc:
      int perform_update(cp_db_connection *_conn, char *query);
    4. a function to close connections:
      int close_connection(cp_db_connection *connection);
  • cprops currently delivers with implementations for postgres and mysql. If you do write an implementation for another dbms system and interested in contributing to libcprops, do not hesitate to contact me at iaelion at users dot sourceforge dot net.