# 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

`db_name`
Name of the database for which to register collation functions.
`colls`
Pointer to a mco_collation_funcs_t structure.

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

`MCO_S_OK`
Collation functions successfully registered (or reassigned).
`MCO_E_INSTANCES_LIMIT`
No free slots available in the collation registry (maximum number of databases reached).

### Files

Header file:
mco.h
Source file:
mcodb.c
Library:
libmcolib.a