基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
OBCI 相关 API 介绍
更新时间:2023-07-18 17:25:58
本文主要介绍 OBCI 常用的 API 函数和示例。
C API 函数概览
当前版本 OBCI 所有可用的 C API 函数如下表所示。
有关各接口详细信息,请参见官网文档 OceanBase Connector/C。
OBCI 对象接口
OBCI 支持的 OCI 内部的常规对象接口如下表所示。
| 对象 | 对象描述 |
|---|---|
| OCIEnv | OCI 环境句柄 |
| OCIError | OCI 错误处理句柄,获取处理过程中错误信息的对象 |
| OCISvcCtx | OCI 服务上下文对象(内存、连接等) |
| OCIStmt | OCI 语句处理对象 |
| OCIBind | OCI 参数变量信息 |
| OCIDefine | OCI 结果变量信息 |
| OCIDescribe | OCI 定义类型信息 |
| OCIServer | OCI 后端 OBServer 对象 |
| OCISession | OCI 连接 Session 信息 |
| OCITrans | OCI 事务对象 |
| OCICPool | OCI CPool 连接池对象 |
| OCIAuthInfo | OCI 连接验证信息 |
| OCILobLocator | OCI Lob 对象,Lob 函数处理 |
| OCIParam | OCI 参数对象,可以获取对象 Meta 信息 |
| OCIRowid | OCI OB Rowid 对象 |
| OCIDate | OCI 日期对象 |
| OCIDateTime | OCI 时间戳对象 |
| OCIInterval | OCI 时间间隔对象 |
| OCINumber | OCI 高精度数据对象 |
| OCIString | OCI 字符串对象 |
OBCI 函数接口
初始化相关
处理初始化、连接认证等相关的函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCIEnvCreate | 创建并初始化环境句柄。 |
| OCIEnvNlsCreate | 创建并初始化一个环境句柄,以使其在 OCI 函数下工作。它是 OCIEnvCreate() 函数的增强版本。 |
| OCIEnvInit | 分配并初始化环境句柄。 |
| OCIInitialize | 初始化 OCI 应用环境, OCI 会在这个函数中初始化内部的全局变量和加载一些配置信息。 |
| OCILogoff | 断开通过 OCILogon/OCILogon 与服务器建立的连接。 |
| OCILogon | 根据用户名和密码,登录到一个指定的数据库服务上,并初始化相关的上下文句柄。 |
| OCILogon2 | 根据用户名和密码,登录到一个指定的数据库服务上,并初始化相关的上下文句柄,可以使用 CPOOL 连接进行处理。 |
| OCIServerAttach | 附加一个数据库服务到指定的连接句柄上。 |
| OCIServerDetach | 解除连接句柄和数据库服务名之间的关联。 |
| OCISessionBegin | 使用登录信息在指定的上下文句柄上打开与数据库服务的连接。 |
| OCISessionEnd | 结束 OCISessionBegin() 函数中上下文句柄与数据库服务之间的连接。 |
| OCIPing | 确定连接和服务处于活动状态。只有服务运行且连接存在时才成功。 |
| OCITerminal | 终止线程中处理。 |
对象初始化相关
Handle 和 Descriptor 的相关函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCIAttrGet | 获取句柄上的属性值。 |
| OCIAttrSet | 设置句柄的属性。 |
| OCIDescriptorAlloc | 分配一个存贮大字段描述符句柄。 |
| OCIDescriptorFree | 释放 OCIDescriptorAlloc() 生成的描述符。 |
| OCIHandleAlloc | 分配和初始化各种句柄。 |
| OCIHandleFree | 释放由 OCIHandleAlloc() 所分配的句柄。 |
| OCIParamGet | 获取描述符句柄上指定位置的描述符句柄。 |
参数绑定结果处理相关
Bind、Define 和 Describe 等参数、结果集空间的相关函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCIBindArrayOfStruct | 以数组方式进行参数绑定。 |
| OCIBindByName | 按参数名称绑定 SQL 语句中的参数(同名只需要绑定一次)。 |
| OCIBindByPos | 按参数在 SQL 语句中出现的位置进行绑定。 |
| OCIDefineArrayOfStruct | 以数组方式进行结果列绑定。 |
| OCIDefineByPos | 按位置来绑定查询返回结果集中每一列的取值空间。 |
请求语句处理相关
语句处理相关函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCIStmtPrepare | 准备一条 SQL 语句,初始化 Stmtp 对象,随后调用 OCIStmtExecute() 来执行。 |
| OCIStmtExecute | 执行准备好的语句。 |
| OCIStmtFetch | 提取 SQL 生成的结果集中的行集。当执行一条查询以后,可以多次调用该函数来返回结果集中的所有行,直到该函数返回 OCI_NO_DATA。 |
| OCIStmtRelease | 释放通过调用 OCIStmtPrepare2() 获得的语句句柄。 |
事务处理相关
事务处理相关函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCITransStart | 启动事务。 |
| OCITransCommit | 提交 SQL 的执行动作。 |
| OCITransRollback | 回滚 SQL 的执行动作。 |
数据类型相关
各种数据类型相关的函数如下表所示。
| 数据对象 | 函数 | 函数描述 |
|---|---|---|
| OCIString | OCIStringAllocSize | 获取以代码点(Unicode)或字节为单位的字符串内存分配大小。 |
| OCIString | OCIStringAssign | 将一个字符串分配给另一个字符串。 |
| OCIString | OCIStringAssignText | 将一个字符串分配给另一个字符串。 |
| OCIString | OCIStringPtr | 获取指向给定字符串文本的指针。 |
| OCIString | OCIStringSize | 获取指向给定字符串文本的大小。 |
| OCIString | OCIStringResize | 获取指向给定字符串文本的大小。 |
| OCILoblocator | OCILobGetLength | 返回大字段的长度,按字节计算。 |
| OCILoblocator | OCILobRead | 读取某个大字段中指定长度的内容。 |
| OCILoblocator | OCILobWrite | 连续写入内容到一个大字段存贮描述符中。 |
| OCILoblocator | OCILobLocatorIsInit | 判断给定的 LOB/BFILE 句柄是否已经初始化。 |
| OCILoblocator | OCILobOpen | 打开一个 LOB/BFILE 对象 |
| OCILoblocator | OCILobClose | 关闭一个 LOB/BFILE 对象 |
| OCILoblocator | OCILobIsOpen | 测试一个 LOB/FILE 对象是否已打开。 |
| OCILoblocator | OCILobTrim | 将 LOB 值截短到较短的长度。 |
| OCILoblocator | OCILobTrim2 | 将 LOB 值截断为较短的长度。OceanBase 目前仅支持最大 48M 的 LOB。 |
| OCIDate | OCIDateSysDate | 获取客户端的当前系统日期和时间。 |
| OCIDate | OCIDateToText | 将日期类型转换为指定格式字符串。 |
| OCIDate | OCIDateFromText | 根据指定格式将字符串转换为日期类型。 |
| OCIDateTime | OCIDateTimeToText | 根据指定的格式将给定的日期转换为字符串。 |
| OCIDateTime | OCIDateTimeFromText | 根据指定的格式将给定的日期转换为字符串。 |
| OCIDateTime | OCIDateTimeConstruct | 构造一个日期时间。 |
| OCIDateTime | OCIDateTimeGetTime | 从日期时间值中获取时间(小时、分钟、秒和小数秒)。 |
| OCIDateTime | OCIDateTimeGetDate | 获取日期时间值的日期(年,月,日)部分。 |
| OCIDateTime | OCIDateTimeGetTimeZoneOffset | 取日期时间值的时区(小时,分钟)部分。 |
| OCINumber | OCINumberToInt | 将 Oracle NUMBER 类型转换为整数。 |
| OCINumber | OCINumberToReal | 将 Oracle NUMBER 类型转换为实数。 |
| OCINumber | OCINumberToText | 根据指定格式将 Oracle NUMBER 转换为字符串。 |
| OCINumber | OCINumberIsInt | 测试 OCINumber 是否为整数。 |
| OCINumber | OCINumberFromText | 将字符串转换为 Oracle NUMBER。 |
其他函数
常用的一些其他函数如下表所示。
| 函数 | 函数描述 |
|---|---|
| OCIBreak | 该调用将立即终止当前的(异步)运行执行与服务器关联的 OBCI 功能。 |
| OCIClientVersion | 返回运行时客户端库的版本号。 |
| OCIServerVersion | 返回运行时服务端库的版本号。 |
| OCIErrorGet | 在提供的缓冲区中返回错误消息和 OceanBase 错误代码。 |
| OCIPasswordChange | 修改账户密码。 |
| OCIPing | 对服务器进行往返通话,以确认连接和服务器处于活动状态。 |
示例
使用基础接口创建表、查询表、插入数据和更新数据等。
/**********************************************************
* Copyright(C) 2014 - 2020 Alibaba Inc. All Rights Reserved.
*
* Filename: example.c
* Description: ----
* Create: 2021-05-05 10:14:59
* Last Modified: 2021-05-05 10:14:59
***********************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <malloc.h>
#include "oci.h"
/*声明句柄*/
OCIEnv *envhp; /*环境句柄*/
OCISvcCtx *svchp; /*服务环境句柄*/
OCIServer *srvhp; /*服务器句柄*/
OCISession *authp; /*会话句柄*/
OCIStmt *stmthp; /*语句句柄*/
OCIDescribe *dschp; /*描述句柄*/
OCIError *errhp; /*错误句柄*/
OCIDefine *defhp[3]; /*定义句柄*/
OCIBind *bidhp[4]; /*绑定句柄*/
sb2 ind[3]; /*指示符变量*/
/*绑定 SELECT 结果集的参数*/
int szpersonid; /*存储 personid 列*/
text szsex[2]; /*存储 sex 列*/
text szname[10]; /*存储 name 列*/
text szemail[10]; /*存储 mail 列*/
char sql[256]; /*存储执行的 SQL 语句*/
static text* SQL_DROP_TB = (text*)"drop table person";
static text* SQL_CREATE_TB = (text*)"create table person(personid number, sex varchar2(256), name varchar2(256), email varchar2(256))";
void checker(OCIError *errhp, sword status, const char* filename, int line) {
text errbuf[512];
sb4 errcode = 0;
switch (status)
{
case OCI_SUCCESS:
break;
case OCI_SUCCESS_WITH_INFO:
(void) OCIErrorGet((dvoid *)errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), OCI_HTYPE_ERROR);
(void) printf("%s:%d Error - OCI_SUCCESS_WITH_INFO now get is %d:%.*s\n", filename, line, errcode, 512, errbuf);
break;
case OCI_NEED_DATA:
(void) printf("%s:%d Error - OCI_NEED_DATA\n", filename, line);
break;
case OCI_NO_DATA:
(void) printf("%s:%d Error - OCI_NODATA\n", filename, line);
break;
case OCI_ERROR:
(void) OCIErrorGet((dvoid *)errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), OCI_HTYPE_ERROR);
(void) printf("%s:%d Error - now get is %d:%.*s\n", filename, line, errcode, 512, errbuf);
break;
case OCI_INVALID_HANDLE:
(void) printf("%s:%d Error - OCI_INVALID_HANDLE\n", filename, line);
break;
case OCI_STILL_EXECUTING:
(void) printf("%s:%d Error - OCI_STILL_EXECUTE\n", filename, line);
break;
case OCI_CONTINUE:
(void) printf("%s:%d Error - OCI_CONTINUE\n", filename, line);
break;
default:
break;
}
}
#define OCI_CHECK_RET(errhp, function) \
checker(errhp, function, __FILE__, __LINE__)
/************************************************************************/
/*查询 person 表*/
/************************************************************************/
void query_tables() {
sword status = OCI_SUCCESS;
memset(sql, 0, sizeof(sql));
strcpy(sql, "select personid, name, email from person");
/*准备 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, (text *)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT));
/*绑定输出列*/
OCI_CHECK_RET(errhp, OCIDefineByPos(stmthp, &defhp[0], errhp, 1, &szpersonid,
sizeof(szpersonid), SQLT_INT, &ind[0], 0, 0, OCI_DEFAULT));
OCI_CHECK_RET(errhp, OCIDefineByPos(stmthp, &defhp[1], errhp, 2, (ub1 *)szname,
sizeof(szname), SQLT_STR, &ind[1], 0, 0, OCI_DEFAULT));
OCI_CHECK_RET(errhp, OCIDefineByPos(stmthp, &defhp[2], errhp, 3, (ub1 *)szemail,
sizeof(szemail), SQLT_STR, &ind[2], 0, 0, OCI_DEFAULT));
/*执行 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)0, 0, NULL, NULL,
OCI_DEFAULT));
printf("%-10s%-10s%-10s\n", "PERSONID", "NAME", "EMAIL");
while ((status = OCIStmtFetch(stmthp, errhp, 1, OCI_FETCH_NEXT, OCI_DEFAULT)) == OCI_SUCCESS) {
printf("%-10d", szpersonid);
printf("%-10s", szname);
printf("%-10s\n", szemail);
}
if (OCI_NO_DATA != status) {
printf("error ! error ! error ! err=%d\n", status);
} else {
printf("finish fetch data\n");
}
}
void insert_tables() {
memset(sql, 0, sizeof(sql));
strcpy(sql, "insert into person values(:personid,:sex,:name,:email)");
/*准备 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, (text *)sql, strlen(sql), OCI_NTV_SYNTAX,
OCI_DEFAULT));
/*绑定输入列*/
OCI_CHECK_RET(errhp, OCIBindByName(stmthp, &bidhp[0], errhp, (const OraText*)":personid", 9, &szpersonid,
sizeof(szpersonid), SQLT_INT, NULL, NULL, NULL, 0, NULL, 0));
OCI_CHECK_RET(errhp, OCIBindByName(stmthp, &bidhp[1], errhp, (const OraText*)":sex", 4, szsex,
sizeof(szsex), SQLT_STR, NULL, NULL, NULL, 0, NULL, 0));
OCI_CHECK_RET(errhp, OCIBindByName(stmthp, &bidhp[2], errhp, (const OraText*)":name", 5, szname,
sizeof(szname), SQLT_STR, NULL, NULL, NULL, 0, NULL, 0));
OCI_CHECK_RET(errhp, OCIBindByName(stmthp, &bidhp[3], errhp, (const OraText*)":email", 6, szemail,
sizeof(szemail), SQLT_STR, NULL, NULL, NULL, 0, NULL, 0));
/*设置输入参数*/
szpersonid = 1;
memset(szsex, 0, sizeof(szsex));
strcpy((char*)szsex, "M");
memset(szname, 0, sizeof(szname));
strcpy((char*)szname, "obtest");
memset(szemail, 0, sizeof(szemail));
strcpy((char*)szemail, "t@ob.com");
/*执行 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST OCISnapshot *)0, (OCISnapshot *)0, (ub4)OCI_DEFAULT));
/*提交到数据库*/
OCI_CHECK_RET(errhp, OCITransCommit(svchp, errhp, OCI_DEFAULT));
while ((OCIStmtFetch(stmthp, errhp, 1, OCI_FETCH_NEXT, OCI_DEFAULT)) == OCI_SUCCESS) {
printf("%-10d", szpersonid);
printf("%-10s", szsex);
printf("%-10s", szname);
printf("%-10s\n", szemail);
}
printf("finish insert tables\n");
}
void update_tables() {
memset(sql, 0, sizeof(sql));
strcpy(sql, "update person set sex='M',name='test',email='test@mail' WHERE personid=1");
/*准备 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, (text *)sql, strlen(sql), OCI_NTV_SYNTAX,
OCI_DEFAULT));
/*执行 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST OCISnapshot *)0, (OCISnapshot *)0, (ub4)OCI_DEFAULT));
/*提交到数据库*/
OCI_CHECK_RET(errhp, OCITransCommit(svchp, errhp, OCI_DEFAULT));
}
void delete_tables() {
memset(sql, 0, sizeof(sql));
strcpy(sql, "delete from person WHERE personid = :personid");
/*准备 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, (text *)sql, strlen(sql), OCI_NTV_SYNTAX,
OCI_DEFAULT));
/*绑定输入参数*/
szpersonid = 1;
OCI_CHECK_RET(errhp, OCIBindByPos(stmthp, &bidhp[0], errhp, 1, &szpersonid,
sizeof(szpersonid), SQLT_INT, NULL, NULL, NULL, 0, NULL, 0));
/*执行 SQL 语句*/
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST OCISnapshot *)0, (OCISnapshot *)0, (ub4)OCI_DEFAULT));
/*提交到数据库*/
OCI_CHECK_RET(errhp, OCITransCommit(svchp, errhp, OCI_DEFAULT));
}
int main(int argc, char *argv[]) {
char strServerName[50];
char strUserName[50];
char strPassword[50];
/*根据实际,设置服务器,用户名和密码*/
strcpy(strServerName, "192.160.0.1/test");
strcpy(strUserName, "test");
strcpy(strPassword, "test");
/*初始化 OCI 应用环境*/
OCI_CHECK_RET(errhp, OCIInitialize(OCI_DEFAULT, NULL, NULL, NULL, NULL));
/*初始化环境句柄*/
OCI_CHECK_RET(errhp, OCIEnvInit(&envhp, OCI_DEFAULT, 0, 0));
/*分配句柄*/
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&svchp, OCI_HTYPE_SVCCTX, 0, 0));
/*服务器环境句柄*/
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&srvhp, OCI_HTYPE_SERVER, 0, 0));
/*服务器句柄*/
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&authp, OCI_HTYPE_SESSION, 0, 0));
/*会话句柄*/
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&errhp, OCI_HTYPE_ERROR, 0, 0));
/*错误句柄*/
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&dschp, OCI_HTYPE_DESCRIBE, 0, 0));
/*描述符句柄*/
/*连接服务器*/
OCI_CHECK_RET(errhp, OCIServerAttach(srvhp, errhp, (text *)strServerName,
(sb4)strlen(strServerName), OCI_DEFAULT));
/*设置用户名和密码*/
OCI_CHECK_RET(errhp, OCIAttrSet(authp, OCI_HTYPE_SESSION, (text *)strUserName,
(ub4)strlen(strUserName), OCI_ATTR_USERNAME, errhp));
OCI_CHECK_RET(errhp, OCIAttrSet(authp, OCI_HTYPE_SESSION, (text *)strPassword,
(ub4)strlen(strPassword), OCI_ATTR_PASSWORD, errhp));
/*设置服务器环境句柄属性*/
OCI_CHECK_RET(errhp, OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
(dvoid *)srvhp, (ub4)0, OCI_ATTR_SERVER, errhp));
OCI_CHECK_RET(errhp, OCIAttrSet(svchp, OCI_HTYPE_SVCCTX, (dvoid *)authp,
0, OCI_ATTR_SESSION, errhp));
/*创建并开始一个用户会话*/
OCI_CHECK_RET(errhp, OCISessionBegin(svchp, errhp, authp, OCI_CRED_RDBMS, OCI_DEFAULT));
OCI_CHECK_RET(errhp, OCIHandleAlloc(envhp, (dvoid **)&stmthp, OCI_HTYPE_STMT, 0, 0));
/*语句句柄*/
/************************************************************************/
/*创建 person 表*/
/************************************************************************/
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, (text*)SQL_DROP_TB, strlen((char *)SQL_DROP_TB), OCI_NTV_SYNTAX, OCI_DEFAULT));
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, OCI_COMMIT_ON_SUCCESS));
OCI_CHECK_RET(errhp, OCIStmtPrepare(stmthp, errhp, SQL_CREATE_TB, strlen((char *)SQL_CREATE_TB), OCI_NTV_SYNTAX, OCI_DEFAULT));
OCI_CHECK_RET(errhp, OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, OCI_DEFAULT));
/************************************************************************/
/*查询 person 表*/
/************************************************************************/
query_tables();
/************************************************************************/
/*向 person 表插入一条数据*/
/************************************************************************/
insert_tables();
query_tables();
/************************************************************************/
/*更新 person 表*/
/************************************************************************/
update_tables();
query_tables();
/************************************************************************/
/*删除 person 表的 ID 为的数据,首先要在数据库中存在这条记录*/
/************************************************************************/
delete_tables();
query_tables();
/************************************************************************/
/*结束释放资源*/
/************************************************************************/
//结束会话
OCI_CHECK_RET(errhp, OCISessionEnd(svchp, errhp, authp, (ub4)0));
//断开与数据库的连接
OCI_CHECK_RET(errhp, OCIServerDetach(srvhp, errhp, OCI_DEFAULT));
//释放 OCI 句柄
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)dschp, OCI_HTYPE_DESCRIBE));
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)stmthp, OCI_HTYPE_STMT));
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)errhp, OCI_HTYPE_ERROR));
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)authp, OCI_HTYPE_SESSION));
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)svchp, OCI_HTYPE_SVCCTX));
OCI_CHECK_RET(errhp, OCIHandleFree((dvoid *)srvhp, OCI_HTYPE_SERVER));
return 0;
}