ACILobRead()¶

ACILobRead()¶

作用：

读取某个大对象中指定长度的内容

语法：

sword ACILobRead ( ACISvcCtx          *svchp,
                   ACIError           *errhp,
                   ACILobLocator      *locp,
                   ub4                *amtp,
                   ub4                 offset,
                   void               *bufp,
                   ub4                 bufl,
                   void               *ctxp,
                   ACICallbackLobRead (cbfp)
                                      ( void          *ctxp,
                                        const void    *bufp,
                                        ub4            len,
                                        ub1            piece
                                      )
                   ub2                 csid,
                   ub1                 csfrm );

参数：

svchp (IN/OUT)

服务上下文句柄

errhp (IN/OUT)

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

locp (IN/OUT)

指向读数据的大对象描述符指针

amtp (IN/OUT)

该参数为输入输出参数，值可能是字节或字符数。

对于CLOB类型，输入为字符数，输出为bufp中的字节数；对于BLOB或者BFILE类型，输入输出都是字节数；

参数amtp是在以下情况下读取的数据总量：

在流模式下不读取数据（只读取一段数据，不进行轮询或回调）
通过回调以流模式读取数据

如果使用轮询以流模式读取数据，则参数amtp是最后读取的片段的长度。

如果要读取的数量大于缓冲区长度，则假定从输入偏移量到LOB的末尾或直到已读取指定的字节数（以先到者为准）以流模式读取LOB。输入时，如果此值为0，则从输入偏移量到LOB末尾以流模式读取数据。

流模式（通过轮询或回调实现）从输入偏移量顺序读取LOB值。

如果按片段读取数据，则amtp参数始终包含刚读取的片段的长度。

如果定义了回调函数，则每次从管道读取bufl字节时都会调用此回调函数。每一块都写入bufp。

如果未定义回调函数，则返回ACI_NEED_DATA代码。应用程序必须反复调用 ACILobRead 以读取更多的LOB，直到未返回ACI_NEED_DATA代码。如果将片段读取到不同的大小和位置，则每个调用中的缓冲区指针和长度可以不同。

offset (IN)

输入时，这是从LOB值开始的绝对偏移。对于字符LOB（CLOB），它是从LOB开头开始的字符数；对于二进制LOB或BFILE，它是字节数。第一位是1。

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

bufp (N/OUT)

指向缓冲区的指针，在该缓冲区中读取片段。假定已分配内存的长度为buf1。

bufl (IN)

缓冲区的长度（以字节为单位）。当用字符指定amtp参数，而用字节指定bufl参数时，此值不同于CLOB的amtp值。

ctxp (IN)

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

cbfp (IN)

可以注册为每个片段调用的回调。如果为NULL，则为每块返回ACI_NEED_DATA。

回调函数必须返回ACI_CONTINUE才能继续读取。如果返回任何其他错误代码，则将终止LOB读取。

ctxp (IN)

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

bufp (IN/OUT)

片段的缓冲区指针。

len (IN/OUT)

当前片段的长度（以bufp为单位）

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_IMPLICIT。

说明：

将调用指定的一部分LOB或BFILE读入缓冲区。尝试从NULL LOB或BFILE读取是错误的。

对于BFILE，操作系统文件必须存在于服务器上，并且必须已经由 ACILobFileOpen 或 ACILobOpen 使用输入定位器打开了。数据库必须具有读取操作系统文件的权限，并且用户必须具有对目录对象的读取权限。

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

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

要终止 ACILobRead 操作并释放语句句柄，请使用 ACIBreak 调用。

以下内容适用于CLOB的客户端可变宽度字符集：

使用轮询模式时，请确保仅在第一次调用 ACILobRead 时指定amtp和offset参数。在随后的轮询调用中，这些参数将被忽略。

使用回调时，输入到回调中的len参数指示缓冲区中填充了多少字节。在回调处理期间，请检查len参数，因为整个缓冲区不一定完全填充满数据。

以下内容适用于CLOB的客户端固定宽度字符集和服务器端可变宽度字符集：

读取CLOB值时，请在每次调用 ACILobRead 之后查看amtp参数，以查看有多少缓冲区已满。当返回值以字符为单位时（如客户端字符集为固定宽度时），则将该值转换为字节并确定已填充多少缓冲区。使用回调时，请始终检查len参数以查看已填充多少缓冲区。此值始终以字节为单位。

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