ACILobWrite2()¶

ACILobWrite2()¶

作用：

将缓冲区写入LOB。此功能必须用于大小大于4 GB的LOB。

语法：

sword ACILobWrite2 ( ACISvcCtx       *svchp,
                     ACIError        *errhp,
                     ACILobLocator   *locp,
                     aciub8           *byte_amtp,
                     aciub8          *char_amtp,
                     aciub8           offset,
                     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/OUT)

服务上下文句柄

errhp (IN/OUT)

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

locp (IN/OUT)

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

byte_amtp (IN/OUT)

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

char_amtp (IN/OUT)

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

offset (IN)

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

如果使用流式传输（通过轮询或回调），请在第一个调用中指定偏移量；否则，请使用第一个调用中的偏移量。在随后的轮询调用中，将忽略offset参数。使用回调时，没有偏移量参数。

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。如果存在LOB数据，则将其存储在缓冲区中的数据覆盖。可以通过此调用将缓冲区写到LOB中，也可以使用回调或标准轮询方法将其分段提供。

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

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

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

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

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

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

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

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

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

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

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