cprops - c prototyping tools

doxygen documentation

code samples

portability

implementing a cp_dbms driver

cpsvc README

download

SourceForge Project page

header
implementation

Overview

• 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.