ACILobRead2()

ACILobRead2()

作用：

将调用指定的一部分LOB或BFILE读取到缓冲区中。 此功能必须用于大小大于4 GB的LOB。

语法：

sword ACILobRead2 ( ACISvcCtx           *svchp,
                    ACIError            *errhp,
                    ACILobLocator       *locp,
                    aciub8              *byte_amtp,
                    aciub8              *char_amtp,
                    aciub8               offset,
                    void                *bufp,
                    aciub8               bufl,
                    ub1                  piece,
                    void                *ctxp,
                    ACICallbackLobRead2 (cbfp)
                                   ( void          *ctxp,
                                    const 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)

指向需要读取的大对象描述符指针

• byte_amtp (IN/OUT)

输入：要从数据库读取的字节数。经常用于BLOB或BFILE。对于CLOB只当char_amtp为0时起作用。 输出:已经读取到bufp中的字节数。

• char_amtp (IN/OUT)

输入：要从数据库读取的字符数。BLOB忽略。 输出: 读取到bufp中的字符数。对于BLOB不定义。

• offset (IN)

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

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

• bufp (IN)

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

• bufl (IN)

缓冲区的长度（以八位字节为单位）。 当用字符指定amtp参数，而用字节指定bufl参数时，此值不同于CLOB的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)

片段的缓冲区指针。

• lenp (IN/OUT)

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

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

说明：

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

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

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

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

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

以下几点适用于以流模式读取LOB数据：

• 使用轮询模式时，请确保仅在第一次调用 ACILobRead2 时指定char_amtp和byte_amtp以及offset参数。在随后的轮询调用中，将忽略这些参数。如果将byte_amtp和char_amtp都设置为指向零，并且传递了ACI_FIRST_PIECE，则将采用轮询模式，并且将读取数据直到LOB末尾。输出时，byte_amtp给出当前片段读取的字节数。

对于CLOB char_amtp给出当前片断中读取的字符数。

对于CLOB如果不传递char_amtp，则内部将char_amtp计算为byte_amtp / max char width，因此，如果最大char宽度为4，则char_amtp将计算为byte_amtp / 4。因此， ACILobRead2 不会计算每个字符需要多少字节。相反，在最坏的情况下， ACILobRead2 会获取byte_amtp中可以容纳的字符数。要填充缓冲区，请检查byte_amtp参数以查看有多少缓冲区被填充，然后再次调用 ACILobRead2 以获取剩余的字节。

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

• 使用轮询时，请查看byte_amtp参数以查看当前块已填充多少缓冲区。对于CLOB，char_amtp还返回在缓冲区中读取的字符数。

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