ACIBindByName2()

ACIBindByName2()

作用：

在SQL语句或PL / SQL块中的程序变量和占位符之间创建关联。 当客户端上的实际长度超过UB2MAXVAL时，在使用数据类型时，请使用此调用而不是 ACIBindByName 。相对于 ACIBindByName ， ACIBindByName2 的value_sz类型由sb4变为sb8，alenp类型有ub2变成ub4。

语法：

sword ACIBindByName2 ( ACIStmt         *stmtp,
                       ACIBind        **bindpp,
                       ACIError        *errhp,
                       const OraText   *placeholder,
                       sb4              placeh_len,
                       void            *valuep,
                       sb8              value_sz,
                       ub2              dty,
                       void            *indp,
                       ub4             *alenp,
                       ub2             *rcodep,
                       ub4              maxarr_len,
                       ub4             *curelep,
                       ub4              mode );

参数：

• stmtp (IN/OUT)

语句句柄。

• bindpp (IN/OUT)

输出的绑定信息句柄。可以通过该句柄调用 ACIBindArrayOfStruct 函数来设定该参数每行的间隔长度。隐式分配的绑定句柄bindpp的地址。 当释放语句句柄时，将隐式释放该句柄。 该指针的值必须为NULL或有效的绑定句柄地址。

• errhp (IN/OUT)

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

• placeholder (IN)

由其名称指定的占位符，它映射到与语句句柄关联的语句中的变量。 占位符的编码应始终与环境的编码保持一致。 也就是说，如果语句是使用UTF-16编写的，则占位符也是如此。 作为字符串类型参数，占位符应强制转换为（text * ），并以NULL终止。

• placeh_len (IN)

placeholder 占位符的字节长度。

• valuep (IN/OUT)

参数值缓冲区指针，dty参数中指定类型的数据值的地址或数据值的数组。 可以指定数据值数组以映射到PL / SQL表或为SQL多行操作提供数据。 提供绑定值数组时，这在ACI术语中称为数组绑定。

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

如果ACI_ATTR_CHARSET_ID属性设置为ACI_UTF16ID，则假定通过相应的绑定调用传递和接收的所有数据都采用UTF-16编码。

此外，如针对 ACIStmtPrepare2 所指出的那样，字符串类型valuep的默认编码为上次调用 ACIEnvNlsCreate 的charset参数指定的编码，除非您调用 ACIAttrSet 手动重置绑定句柄字符集。

• value_sz (IN)

此绑定变量的任何数据值（使用valuep传递）的最大可能字节大小。 对于数组绑定，这是任何元素的最大大小，而实际大小在alenp参数中指定。 对于其大小对于客户端应用程序未知的描述符，定位符，请使用指向特定类型的指针的大小。 例如，sizeof（ACILobLocator * ）。

• dty (IN)

绑定值的数据类型。对于数据类型SQLT_CHR， ACIBindByPos 在实际长度为0时修剪尾随空白。指定实际长度alenp以防止尾随空白被修剪。

• indp (IN/OUT)

指向指标变量或数组的指针。 对于所有数据类型，这是指向sb2或sb2值数组的指针。对于动态绑定，将忽略indp参数。 如果valuep是OUT参数，则必须将indp设置为指向ACI_IND_NULL。

• alenp (IN/OUT)

指向数组元素实际字节长度的数组的指针。 使用 ACIEnvNlsCreate （推荐的ACI环境句柄创建接口）时，始终期望以字节为单位的alenp长度（对于IN绑定），并以字节为单位返回OUT绑定。 SQLT_VCS（2字节长度的前缀）和SQLT_LVC（4字节长度的前缀）类型中的长度前缀也始终保持相同的处理。使用较旧的ACI环境句柄创建接口（ ACIEnvCreate 或不建议使用的 ACIEnvInit ）时，alenp长度通常以字节为单位。但是，只有在字符集为ACI_UC2ID（= ACI_UTF16ID）或在相应的ACIBind句柄上设置了ACI_ATTR_CHAR_COUNT属性时，IN绑定的字符才会期望长度，OUT绑定的字符也会返回字符长度。 SQLT_VCS（2字节长度的前缀）和SQLT_LVC（4字节长度的前缀）类型中的长度前缀具有相同的处理方式。 对于动态绑定，将忽略此参数。

• rcodep (OUT)

指向列级返回码数组的指针。 对于动态绑定，将忽略此参数

• maxarr_len (IN)

最大数组长度参数（用户数组可以容纳的最大元素数）。 仅用于PL / SQL索引表绑定。

ACI未支持，不能使用.

• curelep (IN/OUT)

当前数组长度参数（指向执行操作之前或之后数组中元素实际数量的指针）。 仅用于PL / SQL索引表绑定。

ACI未支持，不能使用

• mode (IN)

支持的模式类型如下：

• ACI_DEFAULT

默认模式.

• ACI_DATA_AT_EXEC

选择此模式时，value_sz参数定义运行时可以提供的最大数据大小。 应用程序必须准备好随时随地提供ACI库运行时IN数据缓冲区。 通过以下方式之一提供运行时数据：

• 使用用户定义函数的回调，必须在随后的 ACIBindDynamic 调用中进行注册。

• 使用ACI提供的呼叫的轮询机制。 如果未定义回调，则采用此模式。

也可以看看：

ACI中的运行时数据分配和分段操作，有关使用ACI_DATA_AT_EXEC模式的更多信息

当mode设置为ACI_DATA_AT_EXEC时，请不要在主调用中为valuep，indp，alenp和rcodep提供值。 为indp和alenp传递零（0）。 通过使用 ACIBindDynamic 注册的回调函数提供值。

说明：

该调用用于执行基本的绑定操作。绑定在SQL语句或PL / SQL块中的程序变量的地址和占位符之间创建关联。绑定调用还指定要绑定的数据的类型，还可以指示在运行时提供数据的方法。

编码是由绑定句柄使用默认语句句柄中的设置来确定的，或者可以通过显式指定mode参数来覆盖设置。

ACIBindByName 和 ACIBindByName2 也隐式分配bindpp参数指示的绑定句柄。如果在** bindpp中传递了非NULL指针，则ACI会假定该指针指向先前已通过调用 ACIHandleAlloc 或 ACIBindByName 分配的有效句柄。

ACI应用程序中的数据可以静态或动态绑定到占位符。当所有IN绑定数据和OUT绑定缓冲区在执行操作之前都已正确定义时，绑定是静态的。当应用程序在执行时按需向客户端库提供IN绑定数据和OUT绑定缓冲区时，绑定是动态的。通过将此调用的模式参数设置为ACI_DATA_AT_EXEC来指示动态绑定。