支持的 API

📄字数 19.9K

👁️阅读量加载中...

OCIInitialize

功能

初始化 OCI 进程环境。仅做兼容，无实现。

原型

sword OCIInitialize(ub4 mode, const void* ctxp,
                    const void* (*malocfp)(void* ctxp, size_t size),
                    const void* (*ralocfp)(void* ctxp, void* memptr, size_t newsize),
                    const void (*mfreefp)(void* ctxp, void* memptr));

参数

mode：指定初始化模式
ctxp：用户自定义的内存回调上下文
malocfp：用户自定义的内存分配函数
ralocfp：用户自定义的内存分配函数
mfreefp：用户自定义的内存释放函数

示例

OCIInitialize(OCI_DEFAULT, NULL, NULL, NULL, NULL);

OCIEnvInit

功能

分配并初始化一个 OCI 环境句柄。

原型

sword OCIEnvInit(OCIEnv** envhpp, ub4 mode,
                 size_t xtramemsz, void** usrmempp);

参数

envhpp：环境句柄指针的地址
mode：指定初始化环境的模式，未使用
xtramemsz：指定被分配的用户内存总数，单位为字节
usrmempp：返回通过此函数调用分配的用户内存指针

说明

通过 usrmempp 获取的内存与其句柄拥有相同的生命周期，用户无需且不可自行释放此内存。

示例

OCIEnv* envhp;
if (OCIEnvInit(&envhp, OCI_DEFAULT, 0, NULL) == OCI_SUCCESS) {
    // do something
} else {
    // handle error
}

OCIEnvCreate

功能

创建并初始化一个环境句柄。

原型

sword OCIEnvCreate(OCIEnv** envp, ub4 mode, void* ctxp,
                   void* (*malocfp)(void* ctxp, size_t size),
                   void* (*ralocfp)(void* ctxp, void* memptr, size_t newsize),
                   void  (*mfreefp)(void* ctxp, void* memptr),
                   size_t xtramem_sz, void** usrmempp);

参数

envp：环境句柄指针的地址
mode：指定初始化模式，未使用
ctxp：指定用户定义的内存回调上下文
malocfp：指定用户自定义的内存分配函数
ralocfp：指定用户自定义的内存重新分配函数
mfreefp：指定用户自定义的内存释放函数
xtramem_sz：指定分配的用户内存数，单位为字节
usrmempp：返回分配的用户内存指针

说明

若调用此接口指定了自定义的内存函数，调用参数含有 xtramem_sz 和 usrmempp 的接口时，将使用用户自定义的内存函数。

通过 usrmempp 获取的内存与其句柄拥有相同的生命周期，用户无需且不可自行释放此内存。

示例

OCIEnv* envhp;
if (OCIEnvCreate(&envhp, OCI_DEFAULT, NULL, NULL, NULL, NULL, 0, NULL) == OCI_SUCCESS) {
    // do something
} else {
    // handle error
}

OCIHandleAlloc

功能

返回一个已分配并已初始化的句柄。

原型

sword OCIHandleAlloc(const void* parenth, void** hndlpp, const ub4 type,
                     const size_t xtramem_sz, void** usrmempp);

参数

parenth：环境句柄
hndlpp：待返回的句柄
type：待返回的句柄类型，支持的类型如下：
- OCI_HTYPE_ENV
- OCI_HTYPE_ERROR
- OCI_HTYPE_SVCCTX
- OCI_HTYPE_STMT
- OCI_HTYPE_SERVER
- OCI_HTYPE_SESSION
xtramem_sz：指定分配的用户内存数
usrmempp：返回分配的用户内存指针

说明

通过 usrmempp 获取的内存与其句柄拥有相同的生命周期，用户无需且不可自行释放此内存。

示例

OCIEnv* env;
OCIServer* server;
OCIError* err;
OCISession* session;
OCISvcCtx* ctx;
OCIStmt* stmt;
OCIEnvCreate(&env, OCI_DEFAULT, NULL, NULL, NULL, NULL, 0, NULL);
OCIHandleAlloc(env, &server, OCI_HTYPE_SERVER, 0, NULL);
OCIHandleAlloc(env, &err, OCI_HTYPE_ERROR, 0, NULL);
OCIHandleAlloc(env, &session, OCI_HTYPE_SESSION, 0, NULL);
OCIHandleAlloc(env, &ctx, OCI_HTYPE_SVCCTX, 0, NULL);
OCIHandleAlloc(env, &stmt, OCI_HTYPE_STMT, 0, NULL);

OCIHandleFree

功能

释放句柄。

原型

sword OCIHandleFree(void* hndlp, const ub4 type);

参数

hndlp：句柄
type：句柄类型

示例

OCIHandleFree(stmt, OCI_HTYPE_STMT);
OCIHandleFree(ctx, OCI_HTYPE_SVCCTX);
OCIHandleFree(session, OCI_HTYPE_SESSION);
OCIHandleFree(err, OCI_HTYPE_ERROR);
OCIHandleFree(server, OCI_HTYPE_SERVER);
OCIHandleFree(env, OCI_HTYPE_ENV);

OCIServerAttach

功能

为 OCI 相关操作创建一个数据库的访问路径。

原型

sword OCIServerAttach(OCIServer* srvhp, OCIError* errhp,
                      const OraText* dblink, sb4 dblink_len, ub4 mode);

参数

srvhp：服务器句柄
errhp：错误句柄
dblink：连接串，如：127.0.0.1:5138/SYSTEM
dblink_len：连接串的长度
mode：指定操作的模式，未使用

示例

const char* serverInfo = "127.0.0.1:5138/SYSTEM";
ret = OCIServerAttach(server, error, (OraText*)serverInfo, strlen(serverInfo), 0);

说明

Oracle OCI 在调用此接口时建立 Socket 连接，若连接信息有误，通过返回值可获得。但 XuguDB-OCI 建立连接和登录数据库是一步操作，在 ServerAttach 时并未连接数据库，因此无法知道连接信息正确与否。

OCIServerDetach

功能

删除 OCI 相关操作一个数据库的访问路径。仅兼容，无实现。

原型

sword OCIServerDetach(OCIServer* srvhp, OCIError* errhp, ub4 mode);

参数

srvhp：已初始化的服务器句柄
errhp：错误句柄
mode：指定操作的模式

示例

OCIServerDetach(server, err, OCI_DEFAULT);

OCIErrorGet

功能

返回错误消息和错误编码。

原型

sword OCIErrorGet(void* hndlp, ub4 recordno, OraText* sqlstate,
                  sb4* errcodep, OraText* bufp, ub4 bufsiz, ub4 type);

参数

hndlp：错误句柄
recordno：指示状态记录，从1开始
sqlstate：8.x 及之后不再支持，未使用
errcodep：错误编码，未使用
bufp：返回错误信息的缓冲区
bufsiz：接收错误信息的缓冲区大小
type：句柄类型

示例

char buf[128];
OCIErrorGet(err, 0, NULL, NULL, (OraText*)buf, 128, OCI_HTYPE_ERROR);

说明

XuguDB-OCI 仅支持 recordno 为 1，否则返回 CI_NO_DATA。type 仅支持 OCI_HTYPE_ERROR 或 OCI_HTYPE_ENV。

OCIAttrSet

功能

为句柄设置属性值。

原型

sword OCIAttrSet(void* trgthndlp, ub4 trghndltyp, void* attributep,
                 ub4 size, ub4 attrtype, OCIError* errhp);

参数

trgthndlp：句柄
trghndltyp：句柄类型
attributep：指向属性值的指针
size：属性值的大小
attrtype：属性类型
errhp：错误句柄

说明

OCI_HTYPE_SVCCTX
- OCI_ATTR_SERVER：设置服务器句柄
- OCI_ATTR_SESSION：设置会话句柄
- OCI_ATTR_CHARSET：设置字符集
OCI_HTYPE_SESSION
- OCI_ATTR_USERNAME：设置用户名
- OCI_ATTR_PASSWORD：设置密码

示例

OCIAttrSet(ctx, OCI_HTYPE_SVCCTX, session, 0, OCI_ATTR_SESSION, err);
OCIAttrSet(session, OCI_HTYPE_SESSION, username, strlen(username), OCI_ATTR_USERNAME, err);
OCIAttrSet(session, OCI_HTYPE_SESSION, pwd, strlen(pwd), OCI_ATTR_PASSWORD, err);

OCIParamGet

功能

从语句句柄中获取指定位置的参数描述符。

原型

sword OCIParamGet(const void* hndlp, ub4 htype, OCIError* errhp,
                  void** parmdpp, ub4 pos);

参数

hndlp：仅支持语句句柄
htype：句柄类型
errhp：错误句柄
parmdpp：参数描述符的地址
pos：语句句柄中的位置

示例

OCIParam* para;
OCIParamGet(stmt, OCI_HTYPE_STMT, err, &para, 1);

OCIAttrGet

功能

获取句柄的属性值。

原型

sword OCIAttrGet(const void* trgthndlp, ub4 trghndltyp,
                 void* attributep, ub4* sizep, ub4 attrtype,
                 OCIError* errhp);

参数

trgthndlp：句柄
trghndltyp：句柄类型
attributep：接收属性值的缓冲区
sizep：属性值大小
attrtype：属性类型
errhp：错误句柄

说明

OCI_HTYPE_DEFINE
- OCI_ATTR_HANDLE_POSITION：获取句柄的列号
OCI_HTYPE_BIND
- OCI_ATTR_HANDLE_POSITION：获取参数的位置编号
OCI_HTYPE_SVCCTX
- OCI_ATTR_SERVER：获取服务器句柄
- OCI_ATTR_SESSION：获取会话句柄
- OCI_HTYPE_SERVER：未支持
OCI_HTYPE_SERVER：未支持
OCI_HTYPE_SESSION
- OCI_ATTR_USERNAME：获取用户名
OCI_HTYPE_STMT
- OCI_ATTR_ROWS_FETCHED：获取已 fetch 的行数
- OCI_ATTR_ROW_COUNT：获取已 fetch 的总行数
- OCI_ATTR_STATEMENT：获取 SQL 语句
- OCI_ATTR_PARAM_COUNT：获取参数个数
OCI_DTYPE_PARAM
- OCI_ATTR_DATA_TYPE：获取数据类型
- OCI_ATTR_DATA_SIZE：获取数据大小

示例

OCIParam* para;
ret = OCIParamGet(stmt, OCI_HTYPE_STMT, err, &para, 1);

ub2 dataType;
text* colName;
ub4 dataSize;
text* typeName;
ub4 colNameLen;
ub4 typeNameLen;
OCIAttrGet(para, OCI_DTYPE_PARAM, &dataType, NULL, OCI_ATTR_DATA_TYPE, err);
OCIAttrGet(para, OCI_DTYPE_PARAM, &colName, &colNameLen, OCI_ATTR_NAME, err);
OCIAttrGet(para, OCI_DTYPE_PARAM, &dataSize, NULL, OCI_ATTR_DATA_SIZE, err);
OCIAttrGet(para, OCI_DTYPE_PARAM, &typeName, &typeNameLen, OCI_ATTR_TYPE_NAME, err);

OCISessionBegin

功能

创建一个用户会话。

原型

swor OCISessionBegin(OCISvcCtx* svchp, OCIError* errhp, OCISession* usrhp,
                     ub4 credt, ub4 mode);

参数

svchp：服务上下文句柄
errhp：错误句柄
usrhp：会话句柄
credt：指定建立用户会话的凭证类型，未使用
mode：指定操作的模式，未使用

说明

XuguDB-OCI 的此接口进行连接的建立和数据库的登录，若连接信息有误，此接口返回错误信息。

示例

OCISessionBegin(ctx, err, session, OCI_CRED_RDBMS, OCI_DEFAULT);

OCISessionEnd

功能

终止一个由 OCISessionBegin 创建的会话上下文。

原型

sword OCISessionEnd(OCISvcCtx* svchp, OCIError* errhp, OCISession* usrhp,
                    ub4 mode);

参数

svchp：服务上下文句柄
errhp：错误句柄
usrhp：会话句柄
mode：仅有效的模式为 OCI_DEFAULT

说明

在中止会话前，若存在未提交的事务，事务将被提交。

示例

OCISessionEnd(ctx, err, session, OCI_DEFAULT);

OCIStmtPrepare

功能

准备一个待执行的 SQL 语句。

原型

sword OCIStmtPrepare(OCIStmt* stmtp, OCIError* errhp, const OraText* stmt,
                     ub4 stmt_len, ub4 language, ub4 mode);

参数

stmtp：语句句柄
errhp：错误句柄
stmt：SQL 语句
stmt_len：SQL 语句长度
language：指定 V7 或本地语法，取值：OCI_V7_SYNTAX、OCI_NTV_SYNTAX、OCI_FOREIGN_SYNTAX，未使用
mode：模式，未使用

示例

cosnt char* sql = "SELECT * FROM tab_test WHERE id = ?";
ret = OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);

OCIDefineByPos

功能

将变量关联到 Select 结果集的列。

原型

sword OCIDefineByPos(OCIStmt* stmtp, OCIDefine** defnp, OCIError* errhp,
                     ub4 position, void* valuep, sb4 value_sz, ub2 dty,
                     void* indp, ub2* rlenp, ub2* rcodep, ub4 mode);

参数

stmtp：语句句柄
defnp：定义句柄
errhp：错误句柄
position：列号，从1开始
valuep：变量的指针
value_sz：变量的大小
dty：数据类型
indp：指向指示器的指针
rlenp：指向数据长度的指针
rcodep：指向列级代码的指针
mode：模式

说明

indp 指向 sb2 类型的变量，在 Oracle 中用于 -1 表示列值为 NULL，0 表示非 NULL，大于 0 表示数据发生截断，其值为列值的实际长度。XuguDB-OCI 暂未兼容此用法。

rcodep 在 Oracle 中指向 ub2 类型变量，但在 XuguDB-OCI 中此参数需指向 sb4 类型变量，且用此变量指示列值是否为 NULL，列值为 NULL 其值为 -1。

若 valuep 为数组时，value_sz 为单个变量大小，indp、rlenp 和 rcodep 均与 valuep 数组元素个数一致。

示例

OCIDefine* def;
int id;
ub2 len;
sb4 rcode;
ret = OCIDefineByPos(stmt, &def, err, 1, &id, 4, SQLT_INT, NULL, &len, &rcode, OCI_DEFAULT);

OCIBindByPos

功能

创建程序变量到 SQL 占位符的关联关系。

原型

sword OCIBindByPos(OCIStmt* stmtp, OCIBind** bindp, OCIError* errhp,
                   ub4 position, void* valuep, sb4 value_sz,
                   ub2 dty, void* indp, ub2* alenp, ub2* rcodep,
                   ub4 maxarr_len, ub4* curelep, ub4 mode);

参数

stmtp：语句句柄
bindp：绑定句柄
errhp：错误句柄
position：占位符的位置，从1开始
valuep：变量的指针
value_sz：变量的大小
dty：数据类型
indp：指向指示器变量的指针
alenp：数据实际大小
rcodep：指向列级代码的数组指针
maxarr_len：最大数组长度，未使用
curelep：当前数组长度，未使用
mode：模式

说明

在 Oracle 中，indp 用于指示列值是否为 NULL，此指针指向 sb2 类型变量，-1 表示 NULL，0 表示非 NULL。alenp 表示列值的实际大小，当取值为 0 时，列值为 NULL。rcodep 用于输出参数。在绑定数组时，valuep、indp、alenp、rcodep 均指向数组，value_sz 为单个变量的大小，maxarr_len 为 0，curelep 为 NULL。

在 XuguDB-OCI 中，对 Oracle 的兼容存在部分问题。列值的实际大小对应 value_sz，而 alenp 未使用。indp 与 Oracle 保持一致。支持数组的绑定，由于 alenp 存在兼容性问题，因此在绑定字符串数组时存在字符串长度无法单个指定的问题。

示例

OCIBind* bind[2];
int id = 1;
char name[20] = "HELLO";
sb2 ind[2] = { 0,0 };
OCIBindByPos(stmt, &bind[0], err, 1, &id, 4, SQLT_INT, &ind[0], NULL, NULL, 0, NULL, OCI_DEFAULT);
OCIBindByPos(stmt, &bind[1], err, 2, name, strlen(name), SQLT_CHR, &ind[1], NULL, NULL, 0, NULL, OCI_DEFAULT);

OCIBindByName

功能

在程序变量与 SQL 占位符间创建关联关系。

原型

sword OCIBindByName(OCIStmt* stmtp, OCIBind** bindp, OCIError* errhp,
                    const OraText* placeholder, sb4 placeh_len,
                    void* valuep, sb4 value_sz, ub2 dty,
                    void* indp, ub2* alenp, ub2* rcodep,
                    ub4 maxarr_len, ub4* curelep, ub4 mode);

参数

stmtp：语句句柄
bindp：指向绑定句柄指针的指针
errhp：错误句柄
placeholder：SQL 占位符
placeh_len：SQL 占位符长度
valuep：变量指针
value_sz：变量的大小
dty：数据类型
indp：指示器变量的指针
alenp：实际大小
rcodep：指向列级代码的指针
maxarr_len：最大数组长度，未使用
curelep：当前数组长度，未使用
mode：模式

说明

示例

const char* sql = "INSERT INTO tab_test(id, name) VALUES(:id, :name)";
OCIStmtPrepare(stmt, err, sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);

OCIBind* bind[2];
int id = 13;
char name[20] = "Tom";
sb2 ind[2] = { 0,0 };
OCIBindByName(stmt, &bind[0], err, "id", 2, &id, 4, SQLT_INT, &ind[0], NULL, NULL, 0, NULL, OCI_DEFAULT);
OCIBindByName(stmt, &bind[1], err, "name", 4, name, strlen(name), SQLT_CHR, &ind[1], NULL, NULL, 0, NULL, OCI_DEFAULT);

OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

OCIStmtExecute

功能

执行已准备的 SQL 语句。

原型

sword OCIStmtExecute(OCISvcCtx* svchp, OCIStmt* stmtp, OCIError* errhp,
                     ub4 iters, ub4 rowoff, const OCISnapshot* snap_in,
                     OCISnapshot* snap_out, ub4 mode);

参数

svchp：服务上下文句柄
stmtp：语句句柄
errhp：错误句柄
iters：DML 语句执行的次数为 iters
rowoff：数组绑定中的数据与此多行执行相关的起始索引，未使用
snap_in：可选参数。如果提供，它必须是指向类型为 OCI_DTYPE_SNAP 的快照描述符的指针，未使用
snap_out：可选参数。如果提供，它必须是指向类型为 OCI_DTYPE_SNAP 的快照描述符的指针，未使用
mode：模式

说明

若 DQL 语句被执行成功，iters 则为获取的数据的行数，相当于在 OCIStmtExecute 中调用了一次 OCIStmtFetch，且为其 nrows 传入了 iters 参数。

若 DML 语句被执行，则此 DML 语句被执行 iters 次。

若 DDL 语句被执行，则此 DDL 语句被执行一次。

若 mode 为 OCI_COMMIT_ON_SUCCESS，在成功调用 execute 后，会提交事务。

示例

const char* sql = "SELECT * FROM tab_test";
OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);
OCIStmtExecute(ctx, stmt, err, 0, 0, NULL, NULL, OCI_DEFAULT);

OCIStmtFetch

功能

从结果集中获取行。

原型

sword OCIStmtFetch(OCIStmt* stmtp, OCIError* errhp, ub4 nrows,
                   ub2 orientation, ub4 mode);

参数

stmtp：语句句柄
errhp：错误句柄
nrows：从当前位置获取的行数
orientation：方向，仅支持 OCI_FETCH_NEXT
mode：仅支持 OCI_DEFAULT

说明

nrows 若大于1，在调用 OCIDefineByPos 时，valuep 等相关参数应传入对应的数组。

示例

const char* sql = "SELECT * FROM tab_test";
ret = OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);
OCIDefine* def;
int id;
ret = OCIDefineByPos(stmt, &def, err, 1, &id, 4, SQLT_INT, NULL, NULL, NULL, OCI_DEFAULT);
ret = OCIStmtExecute(ctx, stmt, err, 0, 0, NULL, NULL, OCI_DEFAULT);
while (TRUE) {
    ret = OCIStmtFetch(stmt, err, 1, OCI_FETCH_NEXT, OCI_DEFAULT);
    if(ret != OCI_SUCCESS)
        break;
}

OCIStmtRelease

功能

释放语句句柄。

原型

sword OCIStmtRelease(OCIStmt* stmtp, OCIError* errhp, const OraText* key,
                     ub4 key_len, ub4 mode);

参数

stmtp：语句句柄
errhp：错误句柄
key：仅对语句缓存有效，在缓存中此关键字被关联到语句，未使用
key_len：仅对语句缓存有效，关键字长度，未使用
mode：模式，未使用

示例

OCIStmtRelease(stmt, err, NULL, 0, OCI_DEFAULT);

OCILogon

功能

创建登录会话，可简化登录步骤。

原型

sword OCILogon(OCIEnv* envhp, OCIError* errhp, OCISvcCtx** svchp,
               const OraText* username, ub4 uname_len,
               const OraText* password, ub4 passwd_len,
               const OraText* dbname, ub4 dbname_len);

参数

envhp：环境句柄
errhp：错误句柄
svchp：服务上下文句柄
username：数据库用户名
uname_len：数据库用户名长度
password：数据库密码
passwd_len：数据库密码长度
dbname：登录的数据库名，或完整连接串
dbname_len：登录的数据库名或连接串长度

说明

参数 dbname 可直接指定登录的数据库名，也可指定所登录数据库的 IP 和端口，如：127.0.0.1:5138/SYSTEM。

示例

const char* username = "SYSDBA";
const char* pwd = "SYSDBA";
const char* db = "SYSTEM";
ret = OCILogon(env, err, &ctx,
                (OraText*)username, strlen(username),
                (OraText*)pwd, strlen(pwd),
                (OraText*)db, strlen(db));

OCILogoff

功能

释放一个由 OCILogon 或 OCILogon2 创建的会话。

原型

sword OCILogoff(OCISvcCtx* svchp, OCIError* errhp);

参数

svchp：服务上下文句柄
errhp：错误句柄

示例

OCILogoff(ctx, err);

OCITransStart

功能

开启事务。

原型

sword OCITransStart(OCISvcCtx* svchp, OCIError* errhp,
                    uword timeout, ub4 flags);

参数

svchp：服务上下文句柄
errhp：错误句柄
timeout：超时时间，未使用
flags：指定是否开启一个新事务或继续使用已存在的事务，未使用

示例

OCITransStart(ctx, err, 0, OCI_TRANS_NEW);

OCITransCommit

功能

提交服务上下文句柄关联的事务。

原型

sword OCITransCommit(OCISvcCtx* svchp, OCIError* errhp, ub4 flags);

参数

svchp：服务上下文句柄
errhp：错误句柄
flags：在全局事务中标志单一提交选项，未使用

示例

OCITransCommit(ctx, err, OCI_DEFAULT);

OCITransRollback

功能

回滚当前事务。

原型

sword OCITransRollback(OCISvcCtx* svchp, OCIError* errhp, ub4 flags);

参数

svchp：服务上下文句柄
errhp：错误句柄
flags：仅支持 OCI_DEFAULT，未使用

示例

OCITransRollback(ctx, err, OCI_DEFAULT);

OCITransDetach

功能

断开事务。仅做兼容，无实现。

原型

sword OCITransDetach(OCISvcCtx* svchp, OCIError* errhp, ub4 flags);

参数

svchp：服务上下文句柄
errhp：错误句柄
flags：仅支持 OCI_DEFAULT

示例

OCITransDetach(ctx, err, OCI_DEFAULT);

OCITerminate

功能

从共享内存中断开进程并释放共享内存。仅做兼容，无实现。

原型

sword OCITerminate(ub4 mode);

参数

mode：仅有效的模式为 OCI_DEFAULT

示例

OCITerminate(OCI_DEFAULT);

OCIDescriptorAlloc

功能

分配描述符。

原型

sword OCIDescriptorAlloc(const void* parenth, void** descpp,
      const ub4 type, const size_t xtramem_sz, void** usrmempp);

参数

parenth：环境句柄
descpp：LOB 定位符地址
type：指定分配描述符还是 LOB 定位符
xtramem_sz：指定描述符生命周期中分配的用户内存数
usrmempp：返回此函数调用分配的用户内存指针

示例

OCILobLocator* lob;
OCIDescriptorAlloc(env, &lob, OCI_DTYPE_LOB, 0, NULL);

OCIDescriptorFree

功能

释放描述符。

原型

sword OCIDescriptorFree(void *descp, ub4 type);

参数

descp：LOB 定位符地址
type：指定分配描述符还是 LOB 定位符

示例

OCILobLocator* lob;
OCIDescriptorAlloc(env, &lob, OCI_DTYPE_LOB, 0, NULL);
OCIDescriptorFree(lob, OCI_DTYPE_LOB);

OCILobRead

功能

从 LOB 中读取一个数据片段。

原型

sword OCILobRead(OCISvcCtx* svchp, OCIError* errhp, OCILobLocator* locp,
                 ub4* amtp, ub4 offset, void* bufp, ub4 bufl, void* ctxp,
                 OCICallbackLobRead cbfp, ub2 csid, ub1 csfrm);

参数

svchp：服务上下文句柄
errhp：错误句柄
locp：Lob 定位符
amtp：实际读取的字节数
offset：偏移量，1为不偏移，仅第一次调用有效，不可小于1
bufp：接收数据的缓冲区
bufl：缓冲区大小
ctxp：回调函数上下文
cbfp：为每一个片段注册的回调函数
csid：缓存数据的字符集 ID
csfrm：缓存数据的字符集形式

说明

回调函数 cbfp 的原型为 sb4 OCICallbackLobRead(void* ctxp, const void* bufp, ub4 len, ub1 piece) 其中

ctxp 为 OCILobRead 参数 ctxp 的传入值
bufp 为 OCILobRead 参数 bufp 的传入值，且已填充数据
len 为当次读取的数据量，小于等于 bufl
piece 为 OCI_FRIST_PIECE、OCI_NEXT_PIECE、OCI_LAST_PIECE

回调函数的返回值必须为 OCI_CONTINUE，否则 OCILobRead 立即终止，且返回 OCI_ERROR。

OCILobRead 返回值：读取完毕返回 OCI_SUCCESS，未读取完毕返回 OCI_NEED_DATA

示例

const char* sql = "SELECT lob FROM tab_test WHERE id = 1";
OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);
OCIDefineByPos(stmt, &def, err, 1, &lob, 0, SQLT_BLOB, NULL, NULL, NULL, OCI_DEFAULT);
OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

ub4 amt;
char buf[1024];
FILE* fp = fopen("lob.png", "wb");

do 
{
    ret = OCILobRead(ctx, err, lob, &amt, 1, buf, 1024, NULL, NULL, 0, SQLCS_IMPLICIT);
    fwrite(buf, 1, amt, fp);
} while (ret == OCI_NEED_DATA);

fclose(fp);

OCILobWrite

功能

将缓冲区的数据写入 LOB。

原型

sword OCILobWrite(OCISvcCtx* svchp, OCIError* errhp, OCILobLocator* locp,
                  ub4* amtp, ub4 offset, void* bufp, ub4 buflen,
                  ub1 piece, void* ctxp, OCICallbackLobWrite cbfp,
                  ub2 csid, ub1 csfrm);

参数

svchp：服务上下文句柄
errhp：错误句柄
locp：Lob 定位符
amtp：总的字节数或字符数
offset：从开始位置的绝对偏移量，1 为不偏移
bufp：数据缓冲区
buflen：缓冲区大小
piece：缓冲区的哪一片，取值为：OCI_ONE_PIECE、OCI_FIRST_PIECE、OCI_NEXT_PIECE、OCI_LAST_PIECE
ctxp：回调函数的上下文
cbfp：为每一片的写入注册回调函数
csid：缓冲区中数据的字符集 ID
csfrm：缓冲区中数据的字符集形式

说明

不分片（OCI_ONE_PIECE）

amtp 为实际写入的字节数，其值需小于等于 buflen。当 offset > 1 时，写入的总字节数为 amtp + offset，偏移的部分补 0。

分片（OCI_FIRST_PIECE、OCIE_NEXT_PIECE、OCIE_LAST_PIECE）

写入 OCI_FIRST_PIECE 时，*amtp 的值为需写入的字节总数，offset 偏移前的数据以 0 填充。若 offset 大于 1，则实际写入的字节数为 *amtp + offset。

写入 OCI_NEXT_PIECE 和 OCI_LAST_PIECE 时，amtp 返回当次写入的字节数，offset 被忽略但其值需大于0。

写入 OCI_NEXT_PIECE 时，写入的字节总数不可大于等于写入 OCI_FIRST_PIECE 时指定的 *amtp 的值。

写入 OCI_LAST_PIECE 时，写入的字节总数不可少于写入 OCI_FIRST_PIECE 时指定的 *amtp 的值。若此时写入的数据大于写入 OCI_FIRST_PIECE 时指定的 *amtp 的值时，将发生截断。

可以不写入 OCI_NEXT_PIECE，但必须写入 OCI_FIRST_PIECE 和 OCI_LAST_PIECE。

回调函数

函数原型为：sword CallbackLobWrite(void* ctxp, void* bufp, ub4* lenp, ub1* piece)

ctxp：为 OCILobWrite 参数 ctxp 的传入值
bufp：为 OCILobWrite 参数 bufp 的传入值
lenp：指向此次写入的字节数的指针
piece：指向此次写入的片信息的指针

调用 OCILobWrite 时，*amtp 的值应为需写入的字节总数，bufp 中的数据为第一片（OCI_FIRST_PIECE）数据。

回调函数中 *piece 的有效取值为 OCI_NEXT_PIECE 和 OCI_LAST_PIECE。

回调函数应返回 OCI_CONTINUE，否则 OCILobWrite 将退出。

示例

const char* sql = "INSERT INTO tab_test (img) VALUES(:img)";
ret = OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);

OCIBind* bind;
ret = OCIBindByPos(stmt, &bind, err, 1, &lob, sizeof(lob), SQLT_BLOB, NULL, NULL, NULL, 0, NULL, OCI_DEFAULT);
ret = OCILobCreateTemporary(ctx, err, lob, OCI_DEFAULT, SQLCS_IMPLICIT, OCI_TEMP_BLOB, FALSE, OCI_DURATION_SESSION);

FILE* fp = fopen(blobFile, "rb");
fseek(fp, 0, SEEK_END);
ub4 blobSize = ftell(fp);
fseek(fp, 0, SEEK_SET);

char* buf = (char*)malloc(blobSize);
fread(buf, 1, blobSize, fp);
fclose(fp);

ret = OCILobWrite(ctx, err, lob, &blobSize, 1, buf, blobSize, OCI_ONE_PIECE, NULL, NULL, OCI_DEFAULT, SQLCS_IMPLICIT);
free(buf);

ret = OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

OCIStmtSetPieceInfo

功能

为分段操作设置分段信息。

原型

sword OCIStmtSetPieceInfo(void* hndlp, ub4 type, OCIError* errhp,
                          const void* bufp, ub4* alenp, ub1 piece,
                          const void* indp, ub2* rcodep);

参数

hndlp：绑定或定义句柄
type：句柄类型
errhp：错误句柄
bufp：数据缓冲区
alenp：缓冲区大小
piece：片段
indp：指向指示器结构体的指针
rcodep：返回码

说明

分片写入在绑定时，可使用 OCIBindByPos 和 OCIBindByName 绑定参数，绑定时需指定序号或者参数名、value_sz、dty，value_sz 指定数据总大小。OCIStmtSetPieceInfo 的总数据大小不可大于在绑定时 value_sz 指定的值，但可小于其值。绑定的模式为：OCI_DATA_AT_EXEC，绑定完成后，需执行一次OCIStmtExecute，其返回值为OCI_NEED_DATA。然后多次调用 OCIStmtSetPieceInfo 和 OCIStmtExecute。

分片读取在绑定时需指定 position、value_sz、dty 和 mode，value_sz 为读取数据的总量其值可大于实际大小，mode 需指定为 OCI_DYNAMIC_FETCH。调用 OCIStmtExecute 其返回值为 OCI_NEED_DATA。使用 OCIStmtSetPieceInfo 传入指向 OCIDefine 的指针，指定数据缓冲区和读取的数据量，调用 OCIStmtFetch 获取数据片段，循环这两个步骤直至取完。若当前行所有的分片数据全部取完，OCIStmtFetch 返回 OCI_SUCCESS，否则返回 OCI_NEED_DATA。若有多个分片字段，无法通过 OCIStmtFetch 的返回值判断当前字段是否取完。可通过 *alenp 的值是否小于原始值判断是否取完当前字段，如果刚好取完，则也无法判断当前字段是否取完。此接口应配合 OCIStmtGetPieceInfo接口一起使用。

示例

sword ret;
const char* sql = "SELECT lob FROM tab_test WHERE id = 1";
ret = OCIStmtPrepare(stmt, err, sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);

int id;
OCIDefine* def;
ret = OCIDefineByPos(stmt, &def, err, 1, NULL, 10000, SQLT_BIN, NULL, NULL, NULL, OCI_DYNAMIC_FETCH);
ret = OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

char buf[1024];
ub4 alen = 1024;
int i = 0;
while (ret == OCI_NEED_DATA)
{
    ret = OCIStmtSetPieceInfo(def, OCI_HTYPE_DEFINE, err, buf, &alen, OCI_NEXT_PIECE, NULL, NULL);
    ret = OCIStmtFetch(stmt, err, 1, OCI_FETCH_NEXT, OCI_DEFAULT);
    printf("第%d段\n", ++i);
}

OCIStmtGetPieceInfo

功能

在分片操作中返回分片信息。

原型

sword OCIStmtGetPieceInfo(const OCIStmt *stmtp, OCIError *errhp,
                          void **hndlpp, ub4 *typep, ub1 *in_outp, ub4 *iterp, 
                          ub4 *idxp, ub1 *piecep );

参数

stmtp：当执行 execute 时返回 OCI_NEED_DATA 的语句句柄
errhp：错误句柄
hndlpp：返回一个指向 bind 或 define 的句柄指针
typep：返回句柄的类型：OCI_HTYPE_BIND 或 OCI_HTYPE_DEFINE
in_outp：返回输入输出类型：OCI_PARAM_IN 或 OCI_PARAM_OUT
iterp：返回多行操作的行数
idxp：PL/SQL 数组绑定操作的数组元素的索引
piecep：返回如下值：OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE, or OCI_LAST_PIECE

示例

const char* sql = "INSERT INTO tab_test (txt1, txt2, txt3) VALUES(:txt1, :txt2, :txt3)";
ret = OCIStmtPrepare(stmt, err, (OraText*)sql, strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);

OCIBind* bind;
ret = OCIBindByPos(stmt, &bind, err, 1, NULL, 30, SQLT_CHR, NULL, NULL, NULL, 0, NULL, OCI_DATA_AT_EXEC);
ret = OCIBindByPos(stmt, &bind, err, 2, NULL, 30, SQLT_CHR, NULL, NULL, NULL, 0, NULL, OCI_DATA_AT_EXEC);
ret = OCIBindByPos(stmt, &bind, err, 3, NULL, 30, SQLT_CHR, NULL, NULL, NULL, 0, NULL, OCI_DATA_AT_EXEC);
ret = OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

const char* data = "123456789012345678901234567890";
const char* p;
const char* end = data + 20;
ub4 alen = 10;

void* hndl;
while (ret == OCI_NEED_DATA)
{
  while (TRUE)
  {
    ret = OCIStmtGetPieceInfo(stmt, err, (void**)&hndl, &type, &inout, &iter, &idx, &piece);
    if (piece == OCI_FIRST_PIECE)
      p = data;
    else if (piece == OCI_NEXT_PIECE)
      p += 10;

    if (p == end)
      piece = OCI_LAST_PIECE;

    ret = OCIStmtSetPieceInfo(hndl, type, err, p, &alen, piece, NULL, NULL);
    ret = OCIStmtExecute(ctx, stmt, err, 1, 0, NULL, NULL, OCI_DEFAULT);

    if (p == end)
      break;
  }
}

ret = OCITransCommit(ctx, err, OCI_DEFAULT);

OCIServerVersion

功能

返回数据库版本字符串。

原型

sword OCIServerVersion(void* hndlp, OCIError* errhp, OraText* bufp,
                       ub4 bufsz, ub1 hndltype);

参数

hndlp：服务上下文句柄
errhp：错误句柄
bufp：返回版本信息的字符缓冲区
bufsz：缓冲区大小
hndltype：句柄类型

说明

在 Oracle 中，句柄类型为 OCI_HTYPE_SERVER 或 OCI_HTYPE_SVCCTX。XuguDB-OCI 不支持从服务器句柄查询服务端版本，仅支持在成功登录数据库后通过上下文句柄获取服务端版本。

示例

char version[30];
ret = OCIServerVersion(ctx, err, version, 30, OCI_HTYPE_SVCCTX);

OCIDateGetDate

功能

从 Oracle date 中获取年、月和日。

原型

void OCIDateGetDate(const OCIDate* date, sb2* year, ub1* month, ub1* day);

参数

date：Oracle 日期
year：返回年
month：返回月
day：返回日

示例

sb2 year;
ub1 month;
ub1 day;
OCIDate date;
OCIDateSetDate(&date, 2021, 11, 1);
OCIDateGetDate(&date, &year, &month, &day);

OCIDateGetTime

功能

从 Oracle date 中获取时间。

原型

void OCIDateGetTime(const OCIDate* date, ub1* hour, ub1* min, ub1* sec);

参数

date：Oracle 日期
hour：返回小时
min：返回分钟
sec：返回秒

示例

ub1 hour;
ub1 minute;
ub1 second;
OCIDate date;
OCIDateSetTime(&date, 14, 30, 20);
OCIDateGetTime(&date, &hour, &minute, &second);

OCIDateSetDate

功能

为 Oracle date 设置日期值。

原型

void OCIDateSetDate(OCIDate* date, sb2 year, ub1 month, ub1 day);

参数

date：Oracle 日期
year：年
month：月
day：日

示例

OCIDate date;
OCIDateSetDate(&date, 2021, 11, 1);

OCIDateSetTime

功能

为 Oracle date 设置时间值。

原型

void OCIDateSetTime(OCIDate* date, ub1 hour, ub1 min, ub1 sec);

参数

date：Oracle 日期
hour：小时
min：分钟
sec：秒

示例

OCIDate date;
OCIDateSetTime(&date, 14, 30, 20);

OCIDateAddDays

功能

在给定的日期加/减天数。

原型

sword OCIDateAddDays(OCIError* err, const OCIDate* date, sb4 num_days,
                     OCIDate* result);

参数

err：错误句柄
date：待加/减的日期
num_days：加/减的天数，负数表示减
result：结果日期

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate date;
OCIDateSetDate(&date, 2021, 11, 1);
OCIDateSetTime(&date, 14, 30, 20);
OCIDate res;
OCIDateAddDays(NULL, &date, 10, &res);

OCIDateAddMonths

功能

在给定的日期上加/减月数。

原型

sword OCIDateAddMonths(OCIError* err, const OCIDate* date, sb4 num_months, OCIDate* result);

参数

err：错误句柄
date：待加/减的日期
num_months：加/减的月数，负数表示减
result：结果日期

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate date;
OCIDateSetDate(&date, 2021, 11, 1);
OCIDateSetTime(&date, 14, 30, 20);
OCIDate res;
OCIDateAddMonths(NULL, &date, 10, &res);

OCIDateAssign

功能

进行日期分配。

原型

sword OCIDateAssign(OCIError* err, const OCIDate* from, OCIDate* to);

参数

err：错误句柄
from：被分配的日期
to：分配的目标

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate date;
OCIDateSetDate(&date, 2021, 11, 1);
OCIDateSetTime(&date, 14, 30, 20);

OCIDate to;
OCIDateAssign(NULL, &date, &to);

OCIDateCompare

功能

比较两个日期的相等性。

原型

sword OCIDateCompare(OCIError* err, const OCIDate* date1,
                     const OCIDate* date2, sword* result);

参数

err：错误句柄
date1：待比较的日期
date2：待比较的日期
result：比较结果，date1 < date2：-1；date1 = date2：0；date1 > date2：1

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate d1, d2;
OCIDateSetDate(&d1, 2021, 11, 10);
OCIDateSetTime(&d1, 14, 30, 20);
OCIDateSetDate(&d2, 2021, 11, 11);
OCIDateSetTime(&d2, 14, 30, 20);
sword res;
OCIDateCompare(NULL, &d1, &d2, &res);

OCIDateLastDay

功能

获取指定日期所在月的最后一天的日期。

原型

sword OCIDateLastDay(OCIError* err, const OCIDate* date,
                     OCIDate* last_day);

参数

err：错误句柄
date：日期
last_day：最后一天的日期

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate d1, d2;
OCIDateSetDate(&d1, 2021, 11, 11);
OCIDateSetTime(&d1, 14, 30, 20);
OCIDateLastDay(NULL, &d1, &d2);

OCIDateSysDate

功能

获取客户端当前的系统日期和时间。

原型

sword OCIDateSysDate(OCIError* err, OCIDate* sys_date);

参数

err：错误句柄
sys_date：当前日期时间

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

示例

OCIDate date;
ret = OCIDateSysDate(NULL, &date);

OCIDateToText

功能

将日期类型转为日期字符串。

原型

sword OCIDateToText(OCIError* err, const OCIDate* date,
                    const oratext* fmt, ub1 fmt_length,
                    const oratext* lang_name, ub4 lang_length,
                    ub4* buf_size, oratext* buf);

参数

err：错误句柄
date：日期
fmt：日期格式
fmt_length：日期格式长度
lang_name：指定语言，未使用
lang_length：语言的长度，未使用
buf_size：缓冲区大小
buf：存放转换后的日期字符串的缓冲区

说明

在 Oracle 中，错误句柄必须传入。在 XuguDB-OCI 中，错误句柄可传入 NULL。

日期格式：

年
- yy 两位年显示值：22
- yyy 三位年显示值：022
- yyyy 四位年显示值：2022
月
- mm 两位月显示值：01
日
- dd 两位日显示值：01
时
- hh 12进制显示值：01
- hh24 24进制显示值：13
分
- mi 两位分显示值：15
秒
- ss 两位秒显示值：45

日期格式字符串可传入 NULL，默认的格式串为 yyyy-mm-dd hh24:mi:ss。

示例

OCIDate date;
OCIDateSetDate(&date, 2022, 7, 1);
OCIDateSetTime(&date, 14, 30, 20);
char buf[30];
ub4 len;
const char* fmt = "yyyy-mm-dd hh24:mi:ss";
OCIDateToText(NULL, &date, fmt, strlen(fmt), NULL, 0, &len, buf);

支持的 API ​

OCIInitialize ​

OCIEnvInit ​

OCIEnvCreate ​

OCIHandleAlloc ​

OCIHandleFree ​

OCIServerAttach ​

OCIServerDetach ​

OCIErrorGet ​

OCIAttrSet ​

OCIParamGet ​

OCIAttrGet ​

OCISessionBegin ​

OCISessionEnd ​

OCIStmtPrepare ​

OCIDefineByPos ​

OCIBindByPos ​

OCIBindByName ​

OCIStmtExecute ​

OCIStmtFetch ​

OCIStmtRelease ​

OCILogon ​

OCILogoff ​

OCITransStart ​

OCITransCommit ​

OCITransRollback ​

OCITransDetach ​

OCITerminate ​

OCIDescriptorAlloc ​

OCIDescriptorFree ​

OCILobRead ​

OCILobWrite ​

OCIStmtSetPieceInfo ​

OCIStmtGetPieceInfo ​

OCIServerVersion ​

OCIDateGetDate ​

OCIDateGetTime ​

OCIDateSetDate ​

OCIDateSetTime ​

OCIDateAddDays ​

OCIDateAddMonths ​

OCIDateAssign ​

OCIDateCompare ​

OCIDateLastDay ​

OCIDateSysDate ​

OCIDateToText ​

支持的 API

OCIInitialize

OCIEnvInit

OCIEnvCreate

OCIHandleAlloc

OCIHandleFree

OCIServerAttach

OCIServerDetach

OCIErrorGet

OCIAttrSet

OCIParamGet

OCIAttrGet

OCISessionBegin

OCISessionEnd

OCIStmtPrepare

OCIDefineByPos

OCIBindByPos

OCIBindByName

OCIStmtExecute

OCIStmtFetch

OCIStmtRelease

OCILogon

OCILogoff

OCITransStart

OCITransCommit

OCITransRollback

OCITransDetach

OCITerminate

OCIDescriptorAlloc

OCIDescriptorFree

OCILobRead

OCILobWrite

OCIStmtSetPieceInfo

OCIStmtGetPieceInfo

OCIServerVersion

OCIDateGetDate

OCIDateGetTime

OCIDateSetDate

OCIDateSetTime

OCIDateAddDays

OCIDateAddMonths

OCIDateAssign

OCIDateCompare

OCIDateLastDay

OCIDateSysDate

OCIDateToText