ACILobWriteAppend()¶

ACILobWriteAppend()¶

作用：

从LOB的末尾开始写入数据（追加数据）。

语法：

sword ACILobWriteAppend ( ACISvcCtx     *svchp,
                          ACIError      *errhp,
                          ACILobLocator *locp,
                          ub4           *amtp,
                          void          *bufp,
                          ub4            buflen,
                          ub1            piece,
                          void          *ctxp,
                          ACICallbackLobWrite       (cbfp)
                                         (
                                           void     *ctxp,
                                           void     *bufp,
                                           ub4      *lenp,
                                           ub1      *piecep
                                         )
                          ub2            csid,
                          ub1            csfrm );

参数：

svchp (IN)

服务上下文句柄

errhp (IN/OUT)

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

locp (IN/OUT)

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

amtp (IN/OUT)

该参数为输入输出参数，当调用函数时，该参数表明想写入的字节数，当函数执行完以后，ACI会回填实际写入的字节数。

输入量是指用户要写入LOB的数据的字节数，而不是bufp中指定的bufp中的字节数。如果将数据分块写入，则写入的字节数可能大于buflen。输出量是指写入服务器端CLOB或NCLOB的字符数。

如果在输入中指定了数量，并且数据是分段写入的，则参数amtp包含调用结束时写入的分段的总长度（最后写入的分段），并且在两者之间未定义。（请注意，它与分段读取的情况不同）。如果未将金额发送给服务器，则会返回错误。如果amtp为零，则采用流模式，并写入数据，直到用户指定ACI_LAST_PIECE。

如果客户端字符集是宽度可变的，则CLOB的输入量以字节为单位，而不是字符。

bufp (IN)

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

buflen (IN)

缓冲区中数据的长度（以字节为单位）。请注意，此参数假定使用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。

csid (IN)

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

csfrm (IN)

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

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

SQLCS_IMPLICIT ：数据库字符集ID

默认值为SQLCS_IMPLICIT。

说明：

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

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

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

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

如果客户端字符集是宽度可变的，则CLOB的输入量以字节为单位，而不是字符。

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

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