ACILobWriteAppend2()¶

ACILobWriteAppend2()¶

作用：

从LOB的末尾开始写入数据。此功能必须用于大小大于4 GB的LOB。

语法：

sword ACILobWriteAppend2 ( ACISvcCtx            *svchp,
                           ACIError             *errhp,
                           ACILobLocator        *locp,
                           aciub8               *byte_amtp,
                           aciub8               *char_amtp,
                           void                 *bufp,
                           aciub8                buflen,
                           ub1                   piece,
                           void                 *ctxp,
                           ACICallbackLobWrite2 (cbfp)
                                       (
                                        void     *ctxp,
                                        void     *bufp,
                                        aciub8   *lenp,
                                        ub1      *piecep
                                        void    **changed_bufpp,
                                        aciub8   *changed_lenp
                                         )
                           ub2                   csid,
                           ub1                   csfrm);

参数：

svchp (IN)

服务上下文句柄

errhp (IN/OUT)

错误句柄，该接口调用失败时，错误信息会存在该句柄上，调用 ACIErrorGet 获得错误信息。

locp (IN/OUT)

指向需要写入的大对象描述符指针

byte_amtp (IN/OUT)

要写入数据库的字节数。经常用于BLOB。对于CLOB和NCLOB只当char_amtp为0时起作用。输出:已经写入数据库的字节数。

char_amtp (IN/OUT)

要写入数据库的最大字符数。BLOB忽略。输出: 已经写入数据库的字符数。对于BLOB不定义。

bufp (IN)

指向从中写入片段的缓冲区的指针。缓冲区中的数据长度假定为buflen中传递的值。即使使用轮询方法将数据分段写入，当调用此调用时，bufp也必须包含LOB的第一部分。如果提供了回调，则不得将bufp用于提供数据。

buflen (IN)

缓冲区中数据的长度（以字节为单位）。当使用char_amtp参数以字符形式指定数量，并且以字节形式指定buflen参数时，此值与CLOB的char_amtp值不同。

该参数假定一个8位字节。如果您的操作系统使用更长的字节，则必须相应地调整buflen的值。

piece (IN)

正在写入缓冲区的哪一部分。此参数的默认值为ACI_ONE_PIECE，指示将缓冲区写入单个块中。对于分段或回调模式，以下其他值也是可能的：ACI_FIRST_PIECE，ACI_NEXT_PIECE和ACI_LAST_PIECE。

ctxp (IN)

回调函数的上下文。可以为NULL。

cbfp (IN)

可以注册的回调，可以在逐段写入中为每段调用。如果为NULL，则使用标准的轮询方法。

回调函数必须返回ACI_CONTINUE才能继续写入。如果返回任何其他错误代码，则LOB写入将终止。回调采用以下参数：

ctxp (IN)

回调函数的上下文。可以为NULL。

bufp (IN/OUT)

片段的缓冲区指针。这与作为输入传递给 ACILobWrite 例程的bufp相同。

lenp (IN/OUT)

缓冲区（IN）中数据的长度（以字节为单位），以及bufp中当前数据的长度（以字节为单位）（OUT）。

piecep (OUT)

可以为：ACI_NEXT_PIECE或ACI_LAST_PIECE。

changed_bufpp (OUT)

如果回调函数倾向于使用新缓冲区供下一部分读取，则可以放置新缓冲区的地址。如果此参数设置为NULL，则使用默认的旧缓冲区bufp。

changed_lenp (OUT)

新缓冲区的长度（如果提供）。

csid (IN)

缓冲区中数据的字符集ID。如果此值为0，则csid设置为客户端的NLS_OSCAR_LANG，具体取决于csfrm的值。

csfrm (IN)

缓冲区数据的字符集形式。 csfrm参数必须与LOB的类型一致。

csfrm参数具有两个可能的非零值：

SQLCS_IMPLICIT ：数据库字符集ID

SQLCS_NCHAR ：NCHAR字符集ID

默认值为SQLCS_IMPLICIT。

说明：

可以通过此调用将缓冲区写到LOB中，也可以使用回调或标准轮询方法将其分段提供。如果piece参数的值为ACI_FIRST_PIECE，则必须通过回调或轮询来提供数据。如果在cbfp参数中定义了一个回调函数，则在将一个段写入管道之后，将调用此回调函数以获取下一个段。每一篇都是从bufp编写的。如果未定义回调函数，则 ACILobWriteAppend2 返回ACI_NEED_DATA错误代码。

应用程序必须再次调用 ACILobWriteAppend2 才能编写更多的LOB。在这种模式下，如果块的大小不同且位置不同，则每次调用中的缓冲区指针和长度可以不同。 ACI_LAST_PIECE的块值将终止分段写入。

如果启用了LOB缓冲，则不支持 ACILobWriteAppend2 。

如果LOB是BLOB，则将忽略csid和csfrm参数。

如果将byte_amtp和char_amtp都设置为指向零量，并且将ACI_FIRST_PIECE用作输入，则将采用轮询模式并写入数据，直到您指定ACI_LAST_PIECE。对于CLOB和NCLOB，byte_amtp和char_amtp分别根据字节数和字符数返回由每段写入的数据。对于BLOB，byte_amtp返回每段写入的字节数，而char_amtp在输出中未定义。

您不必将此LOB操作包装在open或close调用中。如果在执行此操作之前未打开LOB，此操作会隐式打开，完成操作后再关闭。但是，如果您确实在执行此操作之前打开了LOB，则必须在提交或回滚事务之前将其关闭。

如果未将LOB操作包装在打开或关闭API中，则每次写入LOB时都会自动打开和关闭。这会对性能产生不利影响。建议您在open或close语句中包含对LOB的写操作。