ACIDefineByPos2()¶

ACIDefineByPos2()¶

作用：

将选择列表中的项目与类型和输出数据缓冲区关联。当客户端上的实际长度超过UB2MAXVAL时，在处理数据类型时使用此调用。

语法：

sword ACIDefineByPos2 ( ACIStmt     *stmtp,
                        ACIDefine  **defnpp,
                        ACIError    *errhp,
                        ub4          position,
                        void        *valuep,
                        sb8          value_sz,
                        ub2          dty,
                        void        *indp,
                        ub4         *rlenp,
                        ub2         *rcodep,
                        ub4          mode );

参数：

stmtp (IN/OUT)

所请求的SQL查询操作的句柄。

defnpp (IN/OUT)

指向定义句柄的指针的指针。如果将此参数作为NULL传递，则此调用隐式分配定义句柄。为了重新定义，可以在此参数中传递非NULL句柄。该句柄用于存储此列的定义信息。

注意：您必须跟踪此指针。如果对相同的列位置第二次调用 ACIDefineByPos ，则不能保证将返回相同的指针。

errhp (IN/OUT)

当发生错误时，可以将错误句柄传递给 ACIErrorGet 以获取诊断信息。

position (IN)

该值在选择列表中的位置。位置基于1，从左到右编号。值0选择ROWID（表中某行的全局唯一标识符）。

valuep (IN/OUT)

指向dty参数中指定的类型的缓冲区或缓冲区数组的指针。当在单个访存调用中需要多个行的结果时，可以指定多个缓冲区。

对于LOB，缓冲区指针必须是指向ACILobLocator类型的LOB定位器的指针。给出指针的地址。

value_sz (IN)

每个valuep缓冲区的大小（以字节为单位）。如果数据以VARCHAR2格式存储在内部，则可以使用 ACIAttrSet 将所需的字符数（如果不同于以字节为单位的缓冲区大小）指定为附加字节。

如果value_sz的值> SB4MAXVAL，将发出ORA-24452错误，这意味着在版本12.1或更高版本中不支持值> SB4MAXVAL。

在多字节转换环境中，如果指定的字节数不足以处理所需的字符数，则会生成截断错误。

如果ACI_ATTR_CHARSET_ID属性设置为ACI_UTF16ID（代替了不推荐使用的ACI_UCS2ID，保留该属性是为了向后兼容），则假定通过相应的define调用传递和接收的所有数据都采用UTF-16编码。。

dty (IN)

数据类型。仅当环境已在对象模式下初始化时，命名数据类型（SQLT_NTY）和REF（SQLT_REF）才有效。

可以为CLOB列指定SQLT_CHR和SQLT_LNG，可以为BLOB列指定SQLT_BIN和SQLT_LBI。

indp (IN)

指向指标变量或数组的指针。对于标量数据类型，指向sb2或sb2数组的指针。

rlenp (IN/OUT)

指向获取的数据长度数组的指针。

使用 ACIEnvNlsCreate （推荐的ACI环境句柄创建接口）时，一致的长度以字节为单位报告。 SQLT_VCS（2字节长度的前缀）和SQLT_LVC（4字节长度的前缀）类型中的长度前缀也始终保持相同的处理。对于UCS2或NCHAR情况，没有特殊的例外。

使用较旧的ACI环境句柄创建接口（ ACIEnvCreate 或不建议使用的 ACIEnvInit ）时，rlenp长度通常以字节为单位。但是，当字符集为ACI_UC2ID（= ACI_UTF16ID）或在相应的ACIBind句柄上设置了ACI_ATTR_CHAR_COUNT属性时，将以字符返回rlenp长度。 SQLT_VCS（2字节长度的前缀）和SQLT_LVC（4字节长度的前缀）类型中的长度前缀具有相同的处理方式。

rcodep (OUT)

指向列级返回码数组的指针。

mode (IN)

有效模式为：

ACI_DEFAULT-这是默认模式。

ACI_DEFINE_SOFT-软定义模式。此模式可提高通话性能。如果这是第一个定义，或者某些输入参数（例如dty或value_sz）已从先前的定义更改，则将忽略此模式。如果传递了无效的定义句柄，则会导致意外的行为。如果未执行该语句，则返回错误。

ACI_DYNAMIC_FETCH-对于在提取时需要动态分配数据的应用程序，必须使用此模式。您可以使用 ACIDefineDynamic 调用定义回调。 value_sz参数定义运行时要提供的数据的最大大小。当客户端库需要缓冲区以返回获取的数据时，将调用回调以提供运行时缓冲区，将部分或全部数据返回到该运行时缓冲区中。

说明：

该调用定义了一个输出缓冲区，该缓冲区接收从数据库检索到的数据。当SELECT语句将数据返回到ACI应用程序时，定义是本地步骤。

此调用还隐式为选择列表项分配定义句柄。如果在* defnpp中传递了非NULL指针，则ACI会假定它指向先前已通过调用 ACIHandleAlloc 或 ACIDefineByPos 或 ACIDefineByPos2 分配的有效句柄。对于将句柄重新定义到不同地址的应用程序来说，这是正确的，以便它可以将相同的定义句柄重用于多次提取。

在一个或多个调用中完成为获取定义列的属性。第一个调用是对 ACIDefineByPos 或 ACIDefineByPos2 的定义，它们定义了指定访存所需的最小属性。

在对 ACIDefineByPos 或 ACIDefineByPos2 的调用之后，对于某些数据类型或获取模式，可能需要其他定义调用：

必须调用 ACIDefineArrayOfStruct 才能为多列的数组读取设置跳过参数。

必须在 ACIDefineByPos 或 ACIDefineByPos2 之后调用 ACIDefineArrayOfStruct 和ACIDefineObject()，以获取具有指定数据类型的列的多行。

对于LOB定义，缓冲区指针必须是指向由 ACIDescriptorAlloc 调用分配的ACILobLocator类型的LOB定位器的指针。始终为LOB列返回LOB定位符，而不是LOB值。然后，可以在提取的定位器上使用ACI LOB调用来提取LOB值。此相同机制适用于所有描述符数据类型。

在定义描述符或定位符数组时，应传递一个指向描述符或定位符的指针数组。

在为字符列进行数组定义时，应传递一个字符缓冲区数组。

如果此调用中的mode参数设置为ACI_DYNAMIC_FETCH，则客户端应用程序可以在运行时动态获取数据。可以通过以下两种方式之一提供运行时数据：

使用用户定义函数的回调，必须在随后对 ACIDefineDynamic 的调用中进行注册。当客户端库需要缓冲区以返回获取的数据时，将调用回调，并且提供的运行时缓冲区将返回部分或全部数据。

使用ACI提供的呼叫的轮询机制。如果未定义回调，则采用此模式。在这种情况下，提取调用将返回ACI_NEED_DATA错误代码，并且使用分段轮询方法来提供数据。