错误句柄处理接口

错误句柄处理接口是指，当OCI的函数出现错误时，能够通过错误句柄的接口OCIErrorGet获取错误码和错误信息。在此需要分清三个概念：

OCI返回码：是OCI接口返回值，包括如OCI_SUCCESS、OCI_ERROR等。
OCI错误码：是OCI接口返回码错误时，通过OCIErrorGet的errcodep参数获取。
OCI错误信息：是OCI接口返回码错误时，通过OCIErrorGet的bufp参数获取。

OCI返回码

OCI的返回码数量有限，如下列出了所有返回码。

OCI 返回码	值	描述
OCI_SUCCESS	0	The function completed successfully.
OCI_SUCCESS_WITH_INFO	1	The function completed successfully; a call to OCIErrorGet() returns additional diagnostic information. This may include warnings.
OCI_NO_DATA	100	The function completed, and there is no further data.
OCI_ERROR	-1	The function failed; a call to OCIErrorGet() returns additional information.
OCI_INVALID_HANDLE	-2	An invalid handle was passed as a parameter or a user callback was passed an invalid handle or invalid context. No further diagnostics are available.
OCI_NEED_DATA	99	The application must provide runtime data.
OCI_STILL_EXECUTING	-3123	The service context was established in nonblocking mode, and the current operation could not be completed immediately. The operation must be called again to complete. OCIErrorGet() returns ORA-03123 as the error code.
OCI_CONTINUE	-24200	This code is returned only from a callback function. It indicates that the callback function wants the OCI library to resume its normal processing.
OCI_ROWCBK_DONE	-24201	This code is returned only from a callback function. It indicates that the callback function is done with the user row callback.

OCI错误码

OCI错误码是一个sb4类型数据，其中和错误信息一一对应，通过错误可以查找到错误信息。

表1 错误码映射列表

错误码	描述
90000	数组越界param invalid position
90001	绑定参数失败OCI2ODBC_Bind_Mapping not suppot
90002	绑定参数指针错误bindp odbcbpp error
90003	连接用户名或者密码错误dblink or username or password error
90004	OCI官方文档中提到若pos超过字段数，会返回ORA-24334，这里未处理错误码 out of range
90005	分片操作不可用的类型 Is not valid Type
90006	服务上下文句柄为空OCIStmtPrepare svchp is NULL
90007	bad
90008	错误的数据量或者模式Error nrows or orientation or mode
90009	SQLNumParams前后判断前面分析不正确Error binds params
90010	LOB结构体里没有申请内存 null pointer
90011	OCIClose只支持OCI_DTYPE_FILE和OCI_DTYPE_LOB OCILobClose not suppports
90012	Lob没有打开 Lob has not opened
90013	OCI_DTYPE_FILE has not supported to trim
90014	OCILobTrim only supports OCI_DTYPE_LOB
90015	invaile username len or password len or dbname len
90016	Cannot bind keywords
90017	invaild fmt or fmt_length
90018	buffer or buf_size error
90019	invaild out pointer
90020	invalid input param
90021	Temporarily only provide compatibility interface
90022	Please check username, username length, password, password length, old password, old password length.
90023	invalid time value
90024	invalid locp->defnp point
90025	OCILobRead :actul data length is larger than bufl
90026	invaild the length indicator returned by the SQLGetData
91000	无法映射的错误

OCI错误信息

OCI错误信息一个无符号字符数组，包含了OCI接口出错的原因。

OCIErrorGet

功能描述

返回错误消息和 Oracle 数据库错误代码。

功能说明

OCIErrorGet在OCI的函数返回 OCI_ERROR 或 OCI_SUCCESS_WITH_INFO 的 OCI 调用之后调用 OCIErrorGet()，否则 OCIErrorGet() 可能会发现来自某些早期 OCI 调用的错误消息导致错误。为避免此问题，仅应在返回 OCI_ERROR 或 OCI_SUCCESS_WITH_INFO 的 OCI 调用之后调用 OCIErrorGet()。

错误句柄最初是通过调用 OCIHandleAlloc() 分配的。

接口信息

函数/过程

OCIErrorGet的语法如下：

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

参数解释如下：

Hndlp(IN)：通常是错误句柄或环境句柄（ OCIEnvCreate()、OCIHandleAlloc()上的错误）。
recordno(IN)：指示应用程序从中寻找信息的状态记录。从 1 开始。
sqlstate(OUT)：版本 8.x 或更高版本不支持。
errcodep(OUT)：返回的错误代码。
bufp(OUT)：返回的错误消息文本。
bufsiz(IN)：为错误消息提供的缓冲区大小，以字节数为单位。如果错误消息长度大于 bufsiz，则在 bufp 中返回截断的错误消息文本。
- 如果 type 设置为 OCI_HTYPE_ERROR，则 OCIErrorGet() 截断期间的返回码为 OCI_ERROR。然后客户端可以指定更大的缓冲区并再次调用 OCIErrorGet()。
- 如果 bufsiz 足以容纳整个消息文本并且可以成功地将消息复制到 bufp，则 OCIErrorGet() 的返回码是 OCI_SUCCESS。
- 使用以下常量之一定义错误消息缓冲区长度，用户可以在其中从 OCIErrorGet()获取返回的消息：
```
# define OCI_ERROR_MAXMSG_SIZE 1024 /* max size of an error message */
# define OCI_ERROR_MAXMSG_SIZE2 3072 /* new length max size of an error message */
```
type(IN)：句柄的类型（OCI_HTYPE_ERROR 或 OCI_HTYPE_ENV）。

其他说明

无

VastbaseG100