ACILobWrite()¶

ACILobWrite()¶

作用：

连续的写入内容到一个大对象存贮描述符中。

语法：

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

参数：

svchp (IN/OUT)

服务上下文句柄

errhp (IN/OUT)

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

locp (IN/OUT)

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

amtp (IN/OUT)

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

offset (IN)

从大对象开始位置到当前位置的偏移量。对于字符型的LOBs，它是偏移的字符数。对于binary类型的LOBs，它是偏移的字节数。起始位置为1。

bufp (IN)

存放要写的数据缓冲区指针

buflen (IN)

bufp参数指向的缓冲区中的数据长度，以字节为单位。

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参数具有两个可能的非零值：

SQLCS_IMPLICIT ：数据库字符集ID

SQLCS_NCHAR ：NCHAR字符集ID

默认值为SQLCS_IMPLICIT。

说明：

按指定将缓冲区写入内部LOB。如果存在LOB数据，则将其存储在缓冲区中的数据覆盖。可以通过此调用将缓冲区写到LOB中，也可以使用回调或标准轮询方法将其分段提供。

备注：当读取或写入LOB时，请指定与定位器本身的形式匹配的字符集形式（csfrm）。

当您将轮询模式用于 ACILobWrite 时，第一次调用必须指定offset和amtp的值，但是在随后的对 ACILobWrite 的轮询调用中，则无需指定这些值。

如果piece参数的值为ACI_FIRST_PIECE，则可能需要通过回调或轮询来提供数据。

如果在cbfp参数中定义了一个回调函数，则在将一个段写入管道之后，将调用此回调函数以获取下一个段。每一篇都是从bufp编写的。如果未定义回调函数，则 ACILobWrite 返回ACI_NEED_DATA错误代码。应用程序必须再次调用 ACILobWrite 才能编写更多的LOB。在这种模式下，如果块的大小不同且位置不同，则每次调用中的缓冲区指针和长度可以不同。

无论使用轮询还是回调方法，ACI_LAST_PIECE的块值都将终止分段写入。

如果（通过任一输入机制）传递给数据库的数据量小于amtp参数指定的数据量，则返回ORA-22993错误。

此功能仅对内部LOB有效。不允许使用BFILE，因为它们是只读的。如果LOB是BLOB，则将忽略csid和csfrm参数。

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

要以UTF-16格式写入数据，请将csid参数设置为ACI_UTF16ID。如果设置了csid参数，它将覆盖NLS_OSCAR_LANG环境变量。

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

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