Connect、Authorize 和 Initialize 相关函数

更新时间：2025-07-22 16:06:35

OCIEnvCreate

函数功能 ：创建并初始化环境句柄。

函数语法 ：

sword OCIEnvCreate ( OCIEnv **envhpp,
ub4 mode,
CONST dvoid *ctxp,
CONST dvoid (malocfp)
(dvoid *ctxp,
size_t size),
CONST dvoid (ralocfp)
(dvoid *ctxp,
dvoid *memptr,
size_t newsize),
CONST void (*mfreefp)
(dvoid *ctxp,
dvoid *memptr))
size_t xtramemsz,
dvoid **usrmempp );

函数参数 ：

参数	描述
envhpp（ OUT）	用于输出环境句柄。
mode（ IN）	初始化的模式，目前支持 OCI_DEFAULT（默认模式）， OCI_THREADED 多线程模式。
ctxp(IN)	保留兼容，忽略该参数。
malocfp(IN)	保留兼容，忽略该参数。
ralocfp(IN)	保留兼容，忽略该参数。
mfreefp(IN)	保留兼容，忽略该参数。
xtramemsz(IN)	额外附加分配的内存空间。
usrmempp(OUT)	返回额外分配的附加内存空间的地址。

返回值 ：成功时返回 OCI_SUCCESS ，失败时返回 OCI_ERROR，使用无效句柄时返回 OCI_INVALID_HANDLE。

OCIEnvNlsCreate

函数功能 ：创建并初始化一个环境句柄，以使其在 OCI 函数下工作。它是 OCIEnvCreate（）函数的增强版本。

函数原型 ：

sword OCIEnvNlsCreate ( OCIEnv **envhpp,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 xtramemsz,void **usrmempp,ub2  charset,ub2  ncharset );

函数参数 ：

参数	描述
envp(OUT)	环境句柄。
mode(IN)	初始化的模式，目前只支持 OCI_DEFAULT（默认模式）。
ctxp(IN)	保留兼容，忽略该参数。
malocfp(IN)	保留兼容，忽略该参数。
ralocfp(IN)	保留兼容，忽略该参数。
mfreefp(IN)	保留兼容，忽略该参数。
xtramemsz(IN)	额外附加分配的内存空间。
usrmempp(OUT)	返回额外分配的附加内存空间的地址。
charset(IN)	当前环境句柄的客户端字符集。如果为 0，则使用 NLS_LANG 设置。 OCI_UTF16ID 是有效设置，元数据和 CHAR 数据使用它。
ncharset(IN)	当前环境句柄的客户端国家字符集。如果为 0，则使用 NLS_ NCHAR 设置。 OCI_UTF16ID 是有效设置， NCHAR 数据使用它。

返回值 ：成功时返回 OCI_SUCCESS，失败时返回 OCI_ERROR。

OCIEnvInit

函数功能 ：分配并初始化环境句柄。

函数原型 ：

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

函数参数：

参数	描述
envp(OUT)	环境句柄。
mode(IN)	初始化的模式，目前只支持 OCI_DEFAULT（默认模式）。
xtramem_sz(IN)	额外附加分配的内存空间。
usrmempp(IN)	返回额外分配的附加内存空间的地址。

返回值 ：成功时返回 OCI_SUCCESS ，失败时返回 OCI_ERROR。

OCIInitialize

函数功能 ：初始化 OCI 应用环境， 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(IN)	初始化的模式，目前支持 OCI_DEFAULT（默认模式）， OCI_THREADED 多线程模式。
ctxp(IN)	保留兼容，忽略该参数。
malocfp(IN)	保留兼容，忽略该参数。
ralocfp(IN)	保留兼容，忽略该参数。
mfreefp(IN)	保留兼容，忽略该参数。

返回值 ：成功时返回 OCI_SUCCESS ，失败时返回 OCI_ERROR。

OCILogoff

函数功能 ：断开通过 OCILogon 与服务器建立的连接。

函数原型 ：

sword OCILogoff ( 
OCISvcCtx *svchp
OCIError *errhp );

函数参数 ：

参数	描述
svchp(IN)	要断开连接的上下文句柄。
errhp(IN/OUT)	错误信息句柄。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

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(IN)	环境句柄。
errhp(IN/OUT)	错误信息句柄。
svchp(IN/OUT)	上下文句柄。
username(IN)	登录的用户名。
uname_len(IN)	登录的用户名长度。
password(IN)	登录的口令。
passwd_len(IN)	登录的口令长度。
dbname(IN)	数据库服务名。
dbname_len(IN)	数据库服务名长。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

OCIServerAttach

函数功能 ：附加一个数据库服务到指定的连接句柄上。

函数原型 ：

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

函数参数 ：

参数	描述
srvhp(IN)	连接句柄。
errhp(IN/OUT)	错误信息句柄。
dblink(IN)	要关联的数据库服务名。
dblink_len(IN)	数据库服务名的长度。
mode(IN)	附加模式，目前只支持 OCI_DEFAULT。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

OCIServerDetach

函数功能 ：解除连接句柄和数据库服务名之间的关联。

函数原型 ：

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

函数参数 ：

参数	描述
srvhp(IN)	连接句柄。
errhp(IN/OUT)	错误信息句柄。
mode(IN)	附加模式，目前只支持 OCI_DEFAULT （默认模式）。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

OCISessionBegin

函数功能 ：使用登录信息在指定的上下文句柄上打开与数据库服务的连接。

函数原型 ：

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

函数参数 ：

参数	描述
svchp(IN)	指定打开连接的上下文。
errhp(IN/OUT)	错误信息句柄。
usrhp(IN)	登录信息句柄。
credt(IN)	登录的方式, 目前只支持 OCI_CRED_RDBMS -- 通过用户名和口令与数据库服务建立起连接。
mode(IN)	连接模式，目前只支持 OCI_DEFAULT（默认模式）。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

OCISessionEnd

函数功能 ：结束 OCISessionBegin 函数中上下文句柄与数据库服务之间的连接。

函数原型 ：

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

函数参数 ：

参数	描述
svchp(IN)	指定断开连接的上下文。
errhp(IN/OUT)	错误信息句柄。
usrhp(IN)	登录信息句柄。
mode(IN)	连接模式，目前只支持 OCI_DEFAULT（默认模式）。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。

OCIPing

函数功能 ：确定连接和服务处于活动状态。只有服务运行且连接存在时才成功。

函数原型 ：

sword OCIPing (
OCISvcCtx* svchp,
OCIError* errhp,
ub4 mode)

函数参数 ：

参数	描述
svchp (IN)	服务上下文句柄/会话信息句柄。
errhp (IN/OUT)	错误信息句柄。
mode (IN)	时间字符串。

返回值 ：成功返回 OCI_SUCCESS，失败返回 OCI_ERROR。