mco_db_register_collations

RT

Register custom collation functions for a database instance.

Prototype

    MCO_RET mco_db_register_collations(
        /*IN*/ const char *db_name,
        /*IN*/ mco_collation_funcs_h colls
    );

Arguments

Normally colls is a call to the generated function dbname_get_collations() which returns a mco_collation_funcs_t structure initialized with the addresses of a compare and hash function for the specified collation. Stubs for these two collation functions are generated by mcocomp and can then be customized as needed.

Note that after generating a collation file (call it colldb_coll.c) the next time mcocomp is run on this schema a new collation file (colldb_coll.c.new) will be generated with stub functions. This is to avoid overwriting any customizations added to the first collation file.

Description

This function registers collation functions with the runtime when a specific collation order is required for the database. Two callback functions are required: one that is called by the runtime when two database fields (treated as character arrays) are compared, and the second generates a hash.

The function maintains an internal registry (coll_map) that maps database names to collation function sets. If collations are already registered for the given db_name, they are replaced (reassigned).

Requirements:

• Must be called before any indexed string operations occur on the database.
• Collation functions must be thread-safe if used in a multi-threaded environment.
• This feature is only available when MCO_CFG_COLLATION_SUPPORT is defined at compile time.

The maximum number of registered databases is limited by MCO_CFG_DB_MAX_INSTANCES. If this limit is exceeded, the function returns MCO_E_INSTANCES_LIMIT.

Example

    Schema file snippet:

    declare database colldb;

    class Record
    {
        string name;
        uint4  value;

        unique tree <name collate C1> tcoll;
    };

    Collation file (colldb_coll.c) snippet:

    /* collation compare function */
    int2  C1_collation_compare ( mco_collate_h c1, uint2 len1, mco_collate_h c2, uint2 len2)
    {
        /* TODO: add your implementation here */

        return 0;
    }

    Application snippet:

    const char * dbname = "colldb";

    int main(int argc, char* argv[])
    {
        mco_db_h db;
        MCO_RET rc;
        char *mem = malloc( DBSIZE );

        if( (rc = mco_runtime_start()) != MCO_S_OK)
            exit(-1);

        rc = mco_db_open( dbname, simpledb_get_dictionary(), mem, DBSIZE, (uint2)PAGESIZE );

        if( (MCO_S_OK == rc)
        {
            /* register alloc callback */
            mco_register_collations( dbname, colldb_get_collations() );

            /* connect to database */
            rc = mco_db_connect(dbName, &db);
            ...
        }
        ...
    }

Return Codes

Files