大对象接口
限制
在实现clob、blob两种类型时由于数据源内核类型的限制大部分功能在驱动中实现，存在很多限制及不足的情况，故在使用中做出以下限制，同时建议用户非必要不使用此功能。部分接口例如OCILobRead，OCILobWrite等，参数包含无符号整数类型，若传入负数会引发不可预期的问题，请按照类型传入非负数。
在数据绑定时暂时只支持OCIDefineByPos的绑定。
在获取数据是分为轮询和回调，本次只支持轮询。
bfile的字段bfile类型长度不能查过1024，否则会被截取。如“bfile('d_file', 'dad.data')” 不能超过1024。
blob和clob两个只支持简单基表查询， 不支持复杂类型查询,不支持一张表里多列lob场景， 同时不支持clob和blob类型出现在where条件里。
blob的限制需要read和wrtie部分功能。
由于bfile的内核实现必须要open之后才能允许对应的读写操作，故lob的实现(bfile、clob、blob)时需要open之后才能对应的读写等操作。
BFILE类型暂时依赖于vastbase数据库2.2.10及以后的版本。
内核权限要求
- 需要用户创建目录的权限。
- 需要用户执行dbms_lob包的权限。
- 需要用户执行utl_raw包的权限。
OCILobOpen
功能描述
以指定模式打开 LOB (内部或外部)。
功能说明
以指定模式打开 LOB (内部或外部)。
接口信息
函数/过程
OCILobOpen语法如下：
sword OCILobOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub1 mode );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN/OUT)：要打开的 LOB。定位器可以引用内部或外部 LOB。
- mode(IN)：打开 LOB 或 BFILE 的模式。在 Oracle8i 或更高版本中，LOB 的有效模式是：
- OCI_LOB_READONLY：类型CLOB、BLOB、BFILE有效。
- OCI_LOB_READWRITE：类型CLOB、BLOB有效。
其他说明
无
OCILobGetLength
功能描述
获取 LOB 的长度。
功能说明
此函数必须用于大于4GB 的 LOB。
接口信息
函数/过程
OCILobGetLength 语法如下：
sword OCILobGetLength2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *lenp );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN)：唯一引用 LOB 的 LOB 定位器。对于内部 LOB，此定位器必须是从 svchp 指定的服务器获取的定位器。
- lenp (OUT)：它是 LOB 中的字节数。
其他说明
无
OCILobRead
功能描述
将调用指定的 LOB 或 BFILE 的一部分读入缓冲区。
功能说明
不推荐使用此函数。使用 OCILobRead2()。
接口信息
函数/过程
OCILobRead 语法如下：
sword OCILobRead ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
void *bufp,
ub4 bufl,
void *ctxp,
OCICallbackLobRead (cbfp)
( void *ctxp,
const void *bufp,
ub4 len,
ub1 piece
)
ub2 csid,
ub1 csfrm );
参数的解释如下：
- svchp (IN/OUT)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- locp(IN)：唯一引用 LOB 或 BFILE 的 LOB 或 BFILE 定位器。此定位器必须是从 svchp 指定的服务器获取的定位器。
- amtp (IN/OUT)：Amtp 中的值是以字节为单位的长度。
- offset (IN)：这是从 LOB 值开始的绝对偏移量，以字节为单位。
- bufp (IN/OUT)：指向一个缓冲区的指针，该缓冲区中的文件被读入。
- bufl (IN)：缓冲区的长度（以八位为单位）。这个值不同于 CLOB 和 NCLOB 的 amtp 值(csfrm = SQLCS_NCHAR) ，因为amtp参数是以字符为单位指定的，而 bufl 参数是以字节为单位指定的（暂不支持）。
- ctxp (IN)：回调函数的上下文指针。可以为 NULL（暂不支持）。
- cbfp (IN)：一个回调函数，可以注册为针对每个部分调用该函数。如果这是 NULL，那么对于每个片段返回 OCI _ 需要 _ DATA。回调函数必须返回 OCI _ CONTINUE 才能继续读取。如果返回任何其他错误代码，则终止 LOB 读取（暂不支持）。
- ctxp (IN)：回调函数的上下文。可以为 NULL（暂不支持）。
- bufp (IN/OUT)：块的缓冲指针（暂不支持）。
- lenp (IN)：当前块的长度(以字节为单位)（暂不支持）。 piecep (IN)：哪一部分: OCI _ FIRST _ PIECE，OCI _ NEXT _ PIECE，或者 OCI _ LAST _ PIECE（暂不支持）。
- csid (IN)：缓冲区数据的字符集 ID。如果该值为0，则 csid 设置为客户机的 NLS _ LANG 或 NLS _ CHAR 值，具体取决于 csfrm 的值。除非服务器和客户端具有相同的设置，否则绝不假定它是服务器字符集（暂不支持）。
- csfrm (IN)：缓冲区数据的字符集形式。 csfrm 参数必须与 LOB 的类型一致。Csfrm 参数有两个可能的非零值:SQLCS _ IMPLICIT-数据库字符集 ID、SQLCS _ NCHAR-NCHAR 字符集 ID、默认值为 SQLCS _ IMPLICIT。如果未指定 csfrm，则假定为默认值（暂不支持）。
其他说明
无
OCILobWrite
功能描述
将缓冲区写入 LOB。
功能说明
此函数必须用于大于4GB 的 LOB。
接口信息
函数/过程
OCILobWrite 语法如下：
sword OCILobWrite ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
void *bufp,
ub4 buflen,
ub1 piece,
void *ctxp,
OCICallbackLobWrite (cbfp)
(
void *ctxp,
void *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
参数的解释如下：
- svchp (IN/OUT)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN)：唯一引用 LOB 或 BFILE 的 LOB 或 BFILE 定位器。此定位器必须是从 svchp 指定的服务器获取的定位器。
- amtp (IN/OUT)：要写入数据库的字节数。(以字节为单位)。
- offset (IN)：在输入时，它是从 LOB 值开始的绝对偏移量。对于字符 LOB，它是从 LOB 开始的字符数; 对于二进制 LOB，它是字节数。第一个位置是1。如果使用流(通过轮询或回调) ，请在第一次调用中指定偏移量; 在随后的轮询调用中，将忽略偏移量参数。使用回调时，没有偏移量参数。
- bufp (IN)：指向写入块的缓冲区的指针。缓冲区中数据的长度被假定为 buflen 中传递的值。即使使用轮询方法将数据分段写入，当调用此调用时，bufp 也必须包含 LOB 的第一部分。如果提供了回调，则 bufp 不能用于提供数据或错误结果。
- buflen (IN)：缓冲区中数据的长度(以字节为单位)。当使用 char_amtp 参数以字符的形式指定金额，并且 buflen 参数以字节的形式指定时，该值与 CLOB的 char_amtp值不同。
- piece (IN)：正在编写缓冲区的哪一部分。此参数的
- OCI_ONE_PIECE
- OCI_FIRST_PIECE
- OCI_NEXT_PIECE
- OCI_LAST_PIECE
- ctxp (IN)：回调函数的上下文指针。可以为 NULL。
- cbfp (IN)：一种回调，可以注册为在分段写入中为每个片段调用的回调。如果为 NULL，则使用标准轮询方法。回调函数必须返回 OCI_CONTINUE 才能继续写操作。如果返回任何其他错误代码，LOB 写操作将终止。回调接受以下参数（暂不支持）:
- ctxp (IN)：回调函数的上下文。可以为 NULL（暂不支持）。
- bufp (IN/OUT)：块的缓冲指针（暂不支持）。
- lenp (IN)：当前块的长度(以字节为单位)（暂不支持）。
- piecep (IN)：哪一部分（暂不支持）:
- OCI_ONE_PIECE
- OCI_FIRST_PIECE
- OCI_NEXT_PIECE
- OCI_LAST_PIECE
- csid (IN)：缓冲区数据的字符集 ID。如果该值为0，则 csid 设置为客户机的 NLS_LANG 或 NLS_CHAR 值，具体取决于 csfrm 的值。除非服务器和客户端具有相同的设置，否则绝不假定它是服务器字符集（暂不支持）。
- csfrm (IN)：缓冲区数据的字符集形式。 csfrm 参数必须与 LOB 的类型一致。csfrm 参数有两个可能的非零值:SQLCS_IMPLICIT-数据库字符集 ID、SQLCS_NCHAR-NCHAR 字符集 ID、默认值为 SQLCS_IMPLICIT。如果未指定 csfrm，则假定为默认值（暂不支持）。
其他说明
无
OCILobClose
功能描述
关闭先前打开的 LOB 或 BFILE。
功能说明
关闭先前打开的 LOB 或 BFILE。
接口信息
函数/过程
OCILobClose() 语法如下：
sword OCILobClose ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- locp(IN/OUT)：要关闭的 LOB。定位器可以引用内部或外部 LOB。
其他说明
无
OCILobAssign
功能描述
给一个LOB对象赋值。
功能说明
给一个LOB对象赋值为另一个LOB对象。
接口信息
函数/过程
OCILobAssign语法如下：
sword OCILobAssign ( OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *src_locp,
OCILobLocator **dst_locpp );
参数的解释如下：
- envhp (IN)：环境句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- src_locp(IN)：源 LOB对象，用于给目标LOB对象赋值。
- dst_locpp(IN/OUT)：目标LOB对象，需要赋值的LOB对象。
OCILobIsEqual
功能描述
判断LOB对象是否相等。
功能说明
判断两个LOB对象是否相等。
接口信息
函数/过程
OCILobIsEqual 语法如下：
sword OCILobIsEqual ( OCIEnv *envhp,
const OCILobLocator *x,
const OCILobLocator *y,
boolean *is_equal );
参数的解释如下：
- envhp (IN)：环境句柄。
- x(IN)：用来比较的LOB定位器。
- y(IN)：用来比较的LOB定位器。
- is_equal（OUT）：是否相等。
OCILobIsOpen
功能描述
测试 LOB 或 BFILE 是否打开。
功能说明
测试 LOB 或 BFILE 是否打开。
接口信息
函数/过程
OCILobIsOpen 语法如下：
sword OCILobIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
boolean *flag );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- locp(IN)：指向正在检查的 LOB 定位器的指针。定位器可以引用内部或外部 LOB。
- flag (OUT)：如果内部 LOB 是打开的，或者 BFILE 是使用输入定位器打开的，则返回 TRUE。如果不是，返回 FALSE。
其他说明
无
OCILobLocatorIsInit
功能描述
测试以查看是否初始化了给定的 LOB 或 BFILE 定位器。
功能说明
测试以查看是否初始化了给定的 LOB 或 BFILE 定位器。
接口信息
函数/过程
OCILobLocatorIsInit 语法如下：
sword OCILobLocatorIsInit ( OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *locp,
boolean *is_initialized );
参数的解释如下：
- envhp (IN/OUT)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- locp(IN)：正在测试的 LOB 或 BFILE 定位器。
- is_initialized (OUT)：如果给定的 LOB 或 BFILE 定位器已初始化，则返回 TRUE; 如果未初始化，则返回 FALSE。
其他说明
无
OCILobTrim
功能描述
将 LOB 值截断为较短的长度。
功能说明
不推荐使用此函数。请使用 OCILobTrim2()。
接口信息
函数/过程
OCILobTrim 语法如下：
sword OCILobTrim ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN)： LOB 定位器。对于内部 LOB，此定位器必须是从 svchp 指定的服务器获取的定位器。
- newlenp (OUT)：在输出时，如果 LOB 不为 NULL，则为 LOB 的长度。
其他说明
无
OCILobTrim2
功能描述
将 LOB 值截断为较短的长度。
功能说明
此函数必须用于大于4GB 的 LOB。
接口信息
函数/过程
OCILobTrim2 语法如下：
sword OCILobTrim2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 newlen );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET()以获取诊断信息的错误句柄。
- locp(IN/OUT)： LOB 定位器。此定位器必须是从 svchp 指定的服务器获取的定位器。
- newlen (IN)：LOB 值的新长度，它必须小于或等于当前长度。对于字符 LOB，它是字符数。
其他说明
无
OCILobRead2
功能描述
将调用指定的 LOB 或 BFILE 的一部分读入缓冲区。
功能说明
此函数必须用于大于4GB 的 LOB。
接口信息
函数/过程
OCILobRead2 语法如下：
sword OCILobRead2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
oraub8 offset,
void *bufp,
oraub8 bufl,
ub1 piece,
void *ctxp,
OCICallbackLobRead2 (cbfp)
( void *ctxp,
const void *bufp,
oraub8 lenp,
ub1 piecep
void **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm );
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN)： LOB 定位器。此定位器必须是从 svchp 指定的服务器获取的定位器。
- byte_amtp (IN/OUT)：从数据库中读取的字节数。
- char_amtp (IN/OUT)：读入用户缓冲区的最大字符数（暂不支持）。
- offset (IN)：从 LOB 值开始的绝对偏移量的字节数。从1开始。如果轮询 ，请在第一次调用中指定偏移量; 在随后的轮询调用中，将忽略偏移量参数。
- bufp (IN/OUT)：指向一个缓冲区的指针，该缓冲区中的文件被读入。分配的内存的长度被假定为 bufl。
- bufl (IN)：缓冲区的长度(以八位为单位)。这个值不同于 CLOB 和 NCLOB 的 amtp 值(csfrm = SQLCS_NCHAR) ，因为 amtp 参数是以字符为单位指定的，而 bufl 参数是以字节为单位指定的（暂不支持）。
- piece (IN)：OCI_ONE_PIECE-调用从不假设轮询。如果指示的数量大于缓冲区长度，那么缓冲区将被尽可能多地填充。对于轮询，第一次传递OCI_FIRST_PIECE，在随后的调用中传递 OCI_NEXT_PIECE。
- ctxp (IN)：回调函数的上下文指针。可以为 NULL（暂不支持）。
- cbfp (IN)：一个回调函数，可以注册为针对每个部分调用该函数。如果这是 NULL，那么对于每个片段返回 OCI_NEED_DATA。回调函数必须返回 OCI_CONTINUE 才能继续读取。如果返回任何其他错误代码，则终止 LOB 读取（暂不支持）。
- ctxp (IN)：回调函数的上下文。可以为NULL（暂不支持）。
- bufp (IN/OUT)：块的缓冲指针（暂不支持）。
- lenp (IN)：当前块的长度(以字节为单位)（暂不支持）。
- piecep (IN)：有效值（暂不支持）:
- OCI_FIRST_PIECE
- OCI_NEXT_PIECE
- OCI_LAST_PIECE
- changed_bufpp (OUT)：如果回调函数希望使用新的缓冲区来读取下一块，那么它可以放置新缓冲区的地址。如果此参数设置为 NULL，则使用默认的旧缓冲区 bufp（暂不支持）。
- changed_lenp (OUT)：新缓冲区的长度(如果提供的话)（暂不支持）。
- csid (IN)：缓冲区数据的字符集 ID。如果该值为0，则 csid 设置为客户机的 NLS_LANG 或 NLS_CHAR 值，具体取决于 csfrm 的值。除非服务器和客户端具有相同的设置，否则绝不假定它是服务器字符集（暂不支持）。
- csfrm (IN)：缓冲区数据的字符集形式。 csfrm 参数必须与 LOB 的类型一致。csfrm参数有两个可能的非零值:SQLCS_IMPLICIT-数据库字符集 ID、SQLCS_NCHAR-NCHAR 字符集 ID、默认值为 SQLCS_IMPLICIT。如果未指定csfrm，则假定为默认值。
其他说明
无
OCILobCreateTemporary
功能描述
创建临时LOB对象。
功能说明
无。
接口信息
函数/过程
OCILobCreateTemporary 语法如下：
sword OCILobCreateTemporary(OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub2 csid,
ub1 csfrm,
ub1 lobtype,
boolean cache,
OCIDuration duration)
参数的解释如下：
- svchp (IN)：服务上下文句柄。
- errhp(IN/OUT)：出现错误时，可以传递给OCIRRORGET（）以获取诊断信息的错误句柄。
- locp(IN)： LOB 定位器。此定位器必须是从 svchp 指定的服务器获取的定位器。
- csid (IN)：缓冲区数据的字符集 ID。如果该值为0，则 csid 设置为客户机的 NLS_LANG 或 NLS_CHAR 值，具体取决于 csfrm 的值。除非服务器和客户端具有相同的设置，否则绝不假定它是服务器字符集（暂不支持）。
- csfrm (IN)：缓冲区数据的字符集形式。 csfrm 参数必须与 LOB 的类型一致。csfrm参数有两个可能的非零值:SQLCS_IMPLICIT-数据库字符集 ID、SQLCS_NCHAR-NCHAR 字符集 ID、默认值为 SQLCS_IMPLICIT。如果未指定csfrm，则假定为默认值。
- lobtype(IN)：要创建的 LOB 类型。有效值包括:
- OCI_TEMP_BLOB：用于临时 BLOB 的 OCI_TEMP_BLOB。
- OCI_TEMP_CLOB：用于临时 CLOB 的 OCI_TEMP_CLOB。
cache (IN)：如果应该将临时 LOB 读入缓存，则传递 TRUE; 如果不应该，则传递 FALSE。NOCACHE 功能的默认值为 FALSE。（暂不支持）
duration (IN)：临时 LOB 的持续时间。以下是有效值:（暂不支持）
- OCI_DURATION_SESSION
- OCI_DURATION_CALL
其他说明
无
