基于湖库一体架构，统一管理结构化、半结构化与非结构化等多模态数据，一个系统承载事务处理、实时分析与 AI 工作负载。
OBCI
更新时间：2023-07-18 17:25:58
分享
OBCI（ OceanBase Call Interface ）是 OceanBase 架构环境中，与 Oracle OCI 兼容的 C 语言接口调用工具，它提供了与 Oracle OCI 完全兼容的功能特性。
OBCI 介绍
OCI（ Oracle Call Interface ）是 Oracle 公司开发的一个 C 端应用程序开发工具套件，是一个能够访问 Oracle 数据库的服务器，并通过控制各类 SQL 语句的执行，进而控制数据库所有操作的应用程序接口（ API ）。它支持 SQL 所有的数据定义、数据操作、查询和事务管理等操作，支持 C 和 C++ 的数据类型、调用、语法和语义。它提供了一组可对 Oracle 数据库进行存取的接口子例程（函数）。 OBCI 是参照 OCI 的接口标准，结合自身的特点，为开发人员提供向 Oracle 兼容功能的一款接口产品。在接口能力及用户行为上与 Oracle OCI 处理保持一致，满足开发用户在 C 端（ OTL、Tuxdo、ECOB 等）快速访问 OceanBase Oracle 模式集群的需求。
相关概念如下：
OBCI：C 端访问 OceanBase 数据库的一套应用程序接口。
OCI：C 端访问 Oracle 数据库的一套应用程序接口。
libobclient/libobclnt：OBCI 依赖 C 端操作数据库一套访问接口。
OceanBase Oracle模式：OceanBase 数据库兼容 Oracle 语法的处理模式。
OBCI 主要功能
OBCI 使您可以使用 C 语言来访问操作 OceanBase 数据库（ Oracle 模式）中的数据。它以动态链接库（ OCI 库）的形式提供了标准数据库访问和索引功能，应用程序在运行阶段链接此库就可以使用这些功能。
OBCI提供的主要功能如下：
OBCI 提供一套标准的 OceanBase Oracle 数据库访问、处理接口，主要包括数据的定义、数据管理、查询处理、事务控制等。
OBCI 的 API 接口可用于支持可扩展、多线程的应用。
支持 SQL 访问函数。可用于管理数据库访问，处理 SQL 语句，和操作从 OceanBase 数据库服务器获取的对象。
支持数据类型映射和操作函数。可用于操作 OceanBase 数据类型属性。
OBCI 的优势
OBCI 相对于直接通过数据库协议或直接访问 C 接口进行操作 OceanBase 数据库等的有如下优势：
高度封装对数据库访问操作，简化业务实现逻辑。
可以支持第三方框架能力（Tuxdo、OTL 等）。
可以使用 Connection Pool、Statement cache，提高程序的扩展性。
能够支持动态的绑定参数及结果回调函数处理，便于程序动态处理参数及结果数据。
提供暴露 Meta 信息的接口。
提供 DML（ INSERT、UPDATE、DELTE ）中操作访问 Array 等复杂类型数据的能力。
支持 Prefetch 能力，可以减少与后端的交互。
保证线程安全，减少业务对互斥量的使用。
支持的 SQL
Data Definition Language (DDL)
Control Statments：
Transaction Control
Session Control
System Control
Data Manipulation Language（DML)
Queries
PL SQL/Non-block
数据类型
OBCI 支持 OceanBase Oracle 模式下的内部数据类型和 C 语言中 <oci.h> 定义的外部类型（兼容Oracle OCI)。
内部类型
内部类型指的是 OceanBase 数据库 Oracle 模式下可使用的数据类型。
OBCI 支持的常见内部类型如下表所示：
| 名字 | 描述 | 限制 |
|---|---|---|
| char | 固定长度字符串 | 最大长度 2000 |
| varchar2 | 可变长度字符串 | 最大长度 32767 |
| number | 数值类型 | 精度取值范围 1 ~ 38 位数取值范围 -84 ~ 127 |
| int | 整形数值 | 最大值 38 位 |
| binary_float | 32 位浮点数 | 最小值：1.17549E-38F 最大值：3.40282E+38F |
| binary_double | 64 位浮点数 | 最小值：2.22507485850720E-308 最大值：1.79769313486231E+308 |
| date | 日期类型 | YYYY-MM-DD HH:MI:SS |
| timestamp | 时间类型 | YYYY-MM-DD HH:MI:SS [.FFFFFFFFF] |
外部类型
外部类型是用于指定宿主变量存储数据的类型，当输入数据到数据库时，OBCI 会将输入的宿主变量的外部类型和内部数据类型进行转换。当输出数据到外部程序时，OBCI 会将数据库中表的内部数据类型和输出的宿主外部数据类型进行转换。
OBCI 支持的常用外部类型及其对应关系如下表所示：
| 外部类型 | 编码 | 宿主变量数据类型 | OBCI 类型 |
|---|---|---|---|
| VARCHAR2 | 1 | char[n] | SQLT_CHR |
| NUMBER | 2 | unsigned char[21] | SQLT_NUM |
| 8-bit signed INTEGER | 3 | signed char | SQLT_INT |
| 16-bit signed INTEGER | 3 | signed short, signed int | SQLT_INT |
| 32-bit signed INTEGER | 3 | signed int, signed long | SQLT_INT |
| FLOAT | 4 | float, double | SQLT_FLT |
| LONG | 8 | char[n] | SQLT_LNG |
| NULL-terminated STRING | 5 | char[n+1] | SQLT_STR |
| LONG | 8 | char[n] | SQLT_LNG |
| VARCHAR | 9 | char[n+sizeof(short integer)] SQLT_VCS | VARCHAR |
| DATE | 12 | unsigned char[n] | SQLT_BIN |
| RAW | 23 | char[7] | SQLT_DAT |
| CHAR | 96 | char[n] | SQLT_AFC |
| REF | 110 | OCIRef | SQLT_REF |
| Character LOB descriptor | 112 | OCILobLocator (see note 2) | SQLT_CLOB |
| Binary LOB descriptor | 113 | OCILobLocator (see note 2) | SQLT_BLOB |
| ANSI DATE descriptor | 184 | OCIDateTime * | SQLT_DATE |
| TIMESTAMP descriptor | 187 | OCIDateTime * | SQLT_TIMESTAMP |
| TIMESTAMP WITH TIME ZONEdescriptor | 188 | OCIDateTime * | SQLT_TIMESTAMP_TZ |
| TIMESTAMP WITH LOCAL TIME ZONEdescriptor | 232 | OCIDateTime * | SQLT_TIMESTAMP_LTZ |
数据类型转换
在 OBCI 程序中，宿主变量（ Host Variables ）使用了外部数据类型，当从数据库读取数据到外部变量或者将 外部数据存储到数据库中时，会发生数据类型转换。
当前支持的数据类型转换如下表所示：
| VARCHAR2/CHAR | INT | NUMBER | FLOAT | BINARY_FLOAT | BINARY_DOUBLE | DATE | TIMESTAMP | |
|---|---|---|---|---|---|---|---|---|
| CHAR/UNSIGNED CHAR | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| INT/UNSIGNED INT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG/UNSIGNED LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG LONG/UNSIGNED LONG LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| FLOAT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| DOUBLE | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| CHAR[n]/VARCHAR[n]/CHAR* | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN |
说明
对于一些错误下表未标明。如
VARCHAR2转 C 语言CHAR时可能会发生溢出或有非法数字等错误。IN 表示支持从 C 语言转成数据库类型，也就是写入数据到数据库。OUT 表示支持数据库类型转成 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 | 对服务器进行往返通话，以确认连接和服务器处于活动状态。 |
更多信息
有关 OBCI 的详细介绍和使用说明，参见《 OceanBase C 语言调用接口》。
