10.5.2. 多发比对 C 接口
10.5.2.1. 简介
多发比对提供了 C API ，可供 C/C++ 程序直接调用；用户只需要正确地引用 multiplex_client.h 与链接 libmultiplex_client.so 即可使用 C API。
10.5.2.2. 接口说明
要使用 C 接口，您需要发布包中对应操作系统平台的 so 动态库，以及 multiplex_client.h 头文件。
// 目标数据库信息
struct MultiplexTargetDBInfo {
int dbType; // 目标数据库类型，参考:UNISQL_DBTYPE_*宏定义
char* schema; // 目标信创库的库名或schema名
};
// SQL执行绑定变量信息
struct MultiplexPraparedParameter {
char* name; // 绑定变量名称
// 绑定变量类型，参考http接口中《数据类型支持范围》章节
int type;
// 参数值:
// 数值类型(不含numeric): 直接放在value值中, 例如: value = (void *)123;
// 精确数值类型(numeric/number): 以字符串的形式提供，value = "11111222222222.2222222"
// 日期、时间类型: 以字符串形式提供， 格式化样例: "2025-02-25 01:02:03.123"
// 二进制类型: 提供相应内存起始地址
void* value; // 绑定变量值()
// value的长度：
// 如果是字符串类型(含日期,时间类型,精确数值类型)，传入-1，则内部自动调用strlen获取长度;
// 如果是二进制类型(如blob)，则必须传入正确的长度
// 如果是数值类型(不含numeric)，此字段无效
size_t valueLength;
};
// 多发执行结果(调用异常返回一个结果)
struct MultiplexResult {
int code;
char *message; // 返回消息
char* traceId; // 用于查询比对报告的ID
};
struct MultiplexOption {
int batchFlag;
int needTransfer;
};
/**
* @brief 多发初始化
*
* @param serverUrl 多发服务器IP(参考多发HTTP接口)
* @param dbType 多发源数据库类型,参考:UNISQL_DBTYPE_*宏定义
* @param targetDBInfoList 多发目标数据库信息
* @param targetDBInfoListLength 多发目标数据库数量(targetDBInfoList的长度)
* @param handle 多发执行实例(返回参数)，使用完毕需要使用multiplexDestory释放
* @param option 多发选项参数集合
* @return 错误码，0表示成功(其他参考多发http接口错误码章节)
*
* @note
* 1. 同一个handle不要多线程并发使用;
* 2. targetDBInfoList内部会复制一份，此函数返回后，应用可以释放此内存。
*/
extern int multiplexInit(
const char *serverUrl,
int dbType,
MultiplexTargetDBInfo *targetDBInfoList,
unsigned int targetDBInfoListLength,
const MultiplexOption *option,
void **handle);
/**
* @brief 多发实例释放函数
*
* @param multiplexInit函数返回的多发实例句柄
* @return 错误码，0表示成功(其他参考多发http接口错误码章节)
*/
extern int multiplexDestory(void *handle);
/**
* @brief 多发执行SQL
*
* @param handle multiplexInit函数返回的多发实例句柄
* @param traceId 可选，如果没有则传入NULL，服务器会自动生成一个
* @param sql 执行语句
* @param preparedParam 绑定参数列表(如果没有绑定参数则传入NULL)
* @param preparedParamLength 绑定参数列表(如果没有绑定参数则传入0)
* @param result 多发比对执行结果(返回参数)，必须先判断返回值，确认调用成功后再使用此结果。
* @return 错误码，0表示成功(其他参考多发http接口错误码章节)
*
* @note
* 1. 同一个handle不要多线程并发调用此接口
* 2. result由multiplex库内部分配
* 调用成功后，后续务必调用multiplexFree释放内存，调用失败(返回非0)，则无需释放。
*/
extern int multiplexExecute(
void *handle
const char* traceId,
const char *sql,
const MultiplexPraparedParameter *preparedParam,
unsigned int preparedParamLength,
MultiplexResult** result);
/**
* @brief 多发库内存释放函数
* 多发库内部返回的数据结构，需要调用此函数释放，详见其他函数说明
*/
extern void multiplexFree(void *p);
/**
* @brief 多发动态库版本号
*/
extern const char *multiplexVersion();
10.5.2.3. 接口枚举说明
统一 SQL 的 C API 方言编码枚举如下：
#define UNISQL_DBTYPE_LIGHTDB_MYSQL 1 // LIGHTDB MYSQL模式
#define UNISQL_DBTYPE_LIGHTDB_ORACLE 2 // LIGHTDB ORACLE模式
#define UNISQL_DBTYPE_LIGHTDB_POSTGRESQL 3 // LIGHTDB POSTGRESQL模式
#define UNISQL_DBTYPE_DM 4 // 达梦
#define UNISQL_DBTYPE_MYSQL 5 // MYSQL
#define UNISQL_DBTYPE_TDSQL_MYSQL 6 // TDSQL MYSQL模式
#define UNISQL_DBTYPE_MYSQL_80 7 // MYSQL8
#define UNISQL_DBTYPE_OCEAN_BASE_MYSQL 8 // OceanBase MYSQL模式
#define UNISQL_DBTYPE_OCEAN_BASE_ORACLE 9 // OceanBase ORACLE模式
#define UNISQL_DBTYPE_OPENGAUSS 10 // OPENGAUSS
#define UNISQL_DBTYPE_ORACLE 11 // ORACLE
#define UNISQL_DBTYPE_POSTGRESQL 12 // POSTGRESQL
#define UNISQL_DBTYPE_GOLDENDB_MYSQL 13 // GOLDENDB MYSQL模式
#define UNISQL_DBTYPE_GOLDENDB_ORACLE 14 // GOLDENDB ORACLE模式
#define UNISQL_DBTYPE_GAUSSDB_MYSQL 15 // 高斯 MYSQL模式
#define UNISQL_DBTYPE_GAUSSDB_ORACLE 16 // 高斯 ORACLE模式
#define UNISQL_DBTYPE_SQLSVR 17 // SQLSVR模式
#define UNISQL_DBTYPE_TDSQL_PG_ORACLE 18 // tdsql_pg oracle模式
#define UNISQL_DBTYPE_GAUSSDB500_ORACLE 19 // 高斯 ORACLE模式，(GaussDB Kernel V500R002C10 build f6002322)版本
10.5.2.4. 接口返回状态参数
返回类型是一个 int ，取值有 2 种情况：
返回 0: 代表多发比对成功
返回 非0: 代表多发比对异常，可通过错误吗及日志中查看具体失败原因
10.5.2.5. 调用示例
示例代码：
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "multiplex_client.h"
int main() {
// 1. 目标数据库数量
unsigned int targetDBCount = 2;
// 2. 初始化目标数据库类型
MultiplexTargetDBInfo *targetDBInfoList =
(MultiplexTargetDBInfo *)malloc(targetDBCount * sizeof(MultiplexTargetDBInfo));
targetDBInfoList[0].dbtype = UNISQL_DBTYPE_GAUSSDB_ORACLE;
targetDBInfoList[0].scheam = "test";
targetDBInfoList[1].dbtype = UNISQL_DBTYPE_DM;
targetDBInfoList[1].scheam = "test";
// 3. 多发服务器地址
const char *multiplexServerUrl = "http://xxxx:xxx";
// 4. 多发执行实例
void *handle = NULL;
// 5. 初始化实例
MultiplexOption option;
option.batchFlag = 1;
option.needTransfer = 0;
int r = multiplexInit(
multiplexServerUrl,
UNISQL_DBTYPE_ORACLE,
targetDBInfoList,
targetDBCount,
&option,
&handle);
if(r != 0) {
// 错误处理
}
// 6. 多发执行sql
MultiplexResult* result = NULL;
r = multiplexExecute(handle, NULL, "select xxx", NULL, 0, &result);
if(r != 0) {
// 错误处理
}
// 7. 结果处理(result)
// 8. 释放结果集
multiplexFree(result);
// 9. 释放多发执行实例
multiplexDestory(handle);
return 0;
}