Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic


Compare and merge c-treeDB API session dictionaries.


ctdbEXPORT CTDBRET ctdbDECL ctdbMergeSessionDictionary (CTHANDLE src, CTHANDLE dst, mergeFunPtr mrgfun, logFunPtr logfun);



  • src: handle of an exclusively open session where the session dictionary is the dictionary containing the entry to be merged.
  • dst: handle of an exclusively open session where the session dictionary is the target dictionary for the merge.
  • mrgfun: function that the c-treeDB API engine calls to perform the comparison and set the actions on the compared items.

    The function prototype is:

CTDBRET (ctdbDECL *mergeFunPtr) (pCTDBLIST src_list, pCTDBLIST dst_list);

mrgfun must return either an error code (in which case the ctdbMergeSessionDictionary () function will fail with that error code) or CTDBRET_OK if no error occurred.

The c-treeDB API engine will pass two lists (CTDBLIST) containing items of type MERGEINFO. One per each dictionary entry.

The MERGEINFO structure is defined as follows:

struct tagMERGEINFO



NINT todo;


  • info contains the dictionary record.
  • todo must be set to the action to perform on that entry.
  • src_list contains the elements from the source dictionary
  • dst_list contains the elements from the target dictionary.

The function must set for each entry the action to be performed on that entry as follows:

Source List Actions



Ignore the record in the source list and do not copy it on the target dictionary


Copy the record to the target dictionary for entries on the dst_list.

Destination List Actions



Keep the entry as it is.


Remove the entry.


Replace the dest record on disk with the one in the list (in case we merge only some information).
Note: This cannot change the UID.

For example, to replace an entry on the target dictionary with one from the source dictionary, the todo of the item in dsl_list must be set to DIFF_DST_REMOVE, the todo of the item in src_list to DIFF_SRC_COPY2DST.

  • logfun: the function called to return additional information about errors.

    The function prototype is:

VOID (ctdbDECL*logFunPtr) (NINT lvl, pTEXT mesg, CTDBRET error, pTEXT extra);

  • lvl: number indication the error message level. (1 indicating fewer and higher level messages to 3 indicating more numerous detailed messages.)
  • mesg: the error message
  • error: the error code
  • extra: extra information such as the table or database name.

Note: Depending on where an error occurred, this function could be called multiple times with different lvl and mesg.

Return Values

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.


Please review the source code for ctsqlmdd.c, FairCom DB SQL Database Move Utility, for a complete implementation using this c-treeDB API function.

See Also