ACHTUNG: THE CPDO WIKI IS NOW (AS OF 2011-May-17) MAINTAINED ON A DEDICATED WIKI SITE: http://whiki.wanderinghorse.net/wikis/cpdo/?page=DSN

A DSN, or Data Source Name (i think!), is a string which contains information about which database type we want to connect to and driver-specific parameters. They do not contain user/password information - those are provided as explicit connection arguments.

A DSN always starts with the name of the driver responsible for handling it, then a colon, then any driver-specific parameters, as shown in these examples:

See the driver-specific pages for notes about driver-specific DSN parameters: cpdo_sqlite3, cpdo_mysql5

Driver-specific parameters are simple key-value pairs, with each pair being separated by semicolons. Each driver has its own list of options it supports. (Drivers may ignore options they don't understand, for the sake of portability, or may return cpdo_rc.UnsupportedError.) DSNs are not intended to store complex data, like strings which themselves may contain semicolons. Numbers, boolean, and word-like values are fine, however. Boolean values can be set to true by setting them to a value which starts with any of the characters in the set [yYtT1] (the number 1, not the letter el) . All other values are treated as boolean false.

To avoid confusion and subtle incompatibilities regarding case-sensitivity, i now hereby decree that Lower Case is Law, that all option names shall be all lower-case, always, and that lower-case shall be the exclusive form of all option names. Always and forever! Amen!

If you feel you must use a separator character when creating new options, please use an underscore instead of a minus sign, to avoid potential token-parsing confusion later on (an underscore is conventionally legal in identifier strings, whereas minus signs are supported in some metalanguages but not in the vast majority of programming languages).

Example of connecting using a DSN, complete with error handling:

cpdo_driver * db = NULL; // don't forget the NULL!
char const * dsn = "sqlite3:mydb.sqlite";
int rc = cpdo_driver_new_connect( &db, dsn, "user", "passwd" );
if( 0 != rc ) {
    printf("Error #%d (%s)\n", rc, cpdo_rc_string(rc) );
    if( db ) { // this means we found a driver but connection failed
        char const * msg = NULL;
        rc = 0 /* We do this to avoid a potentially confusing corner
                  case in error reporting when error_info() fails.
                  In that case, we would be reporting a cpdo_rc
                  code in place of the DB's (driver-dependent) error code.
        db->api->error_info(db, &msg, NULL, &rc);
        printf("Db error #%d: %s\n", rc, msg );
    return ...;

... use db ... when done, close it ...