数据参数绑定接口

在语句句柄中，为了执行语句，对参数和结果实行绑定，对应的分别为Bind语句和Define句柄。Bind句柄主要为在应用程序变量和SQL语句或PL/SQL块中的占位符之间创建关联。而Define句柄主要是为了获取结果数据。两者关系如下：

输入和输出绑定变量的信息存储在绑定句柄中。OCI库为使用OCIBindByName()或OCIBindByPos()或OCIBindArrayOfStruct()函数绑定的每个占位符分配Bind句柄。用户不得分配绑定句柄。它们由Bind调用隐式分配。

OCIBindByPos

功能描述

在应用程序变量和SQL语句或PL/SQL块中的占位符之间创建关联，通过占位符位置绑定数据。

功能说明

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

此函数还隐式分配bindpp参数指示的绑定句柄。如果在**bindpp中传递了一个非空指针，则OCI假定该指针指向一个有效的句柄，该句柄之前已通过调用OCIHandleAlloc()或OCIBindByPos()分配。

OCI应用程序中的数据可以静态或动态绑定到占位符。在执行操作之前定义好所有绑定内数据和绑定外缓冲区时，绑定是静态的。当应用程序在执行时按需向客户端库提供绑定内数据和绑定外缓冲区时，绑定是动态的。动态绑定是通过设置mode参数为OCI_DATA_AT_EXEC。

接口信息

函数/过程

OCIBindByPos 的语法如下：

sword OCIBindByPos ( OCIStmt       *stmtp, 
                     OCIBind      **bindpp,
                     OCIError      *errhp,
                     ub4            position,
                     void          *valuep,
                     sb4            value_sz,
                     ub2            dty,
                     void          *indp,
                     ub2           *alenp,
                     ub2           *rcodep,
                     ub4            maxarr_len,
                     ub4           *curelep, 
                     ub4            mode );

参数解释如下：

stmtp(IN/OUT)

正在处理的SQL或PL/SQL语句的语句句柄。
bindpp(IN/OUT)

由该调用隐式分配的绑定句柄的地址。绑定句柄维护这个特定输入值的所有绑定信息。当释放语句句柄时，将隐式释放句柄。输入时，指针的值必须为NULL或有效的绑定句柄。
errhp(IN/OUT)

当出现错误时，可以传递给OCIErrorGet()以获取诊断信息的错误句柄。
position(IN)

占位符属性位置指定。从1开始。
valuep(IN/OUT)

一个数据或数组的地址，类型指定在dty参数中，当提供一个绑定值数组时，这在OCI术语中称为数组绑定。
- 当绑定LOB类型时，缓冲区指针必须是指向OCILobLocator 类型的LOB定位器的指针。给出指针的地址。
- 当绑定SQLT_NTY或SQLT_REF类型时，valuep参数被忽略。指向OUT缓冲区的指针在由OCIBindObject()初始化的pgvpp参数中设置。
- 当OCI_ATTR_CHARSET_ID属性设置为OCI_UTF16ID（替换不推荐使用的OCI_UCS2ID，该属性保留用于向后兼容），则传递给相应绑定调用并使用相应绑定调用接收的所有数据都假定为UTF-16编码。
- 当mode设置为OCI_IOV时，传递OCIIOV结构的基址。
value_sz(IN)

此绑定变量的任何数据值（使用valuep传递）的最大可能大小（以字节为单位）。此大小始终应为字节大小。在数组绑定的情况下，这是任何元素可能的最大大小，实际大小在alenp参数中指定。
dty(IN)

要绑定的值的数据类型。
- 当应用程序已在对象模式下初始化时，数据类型（SQLT_NTY）和引用（SQLT_REF）才有效。
- 对于指定数据类型SQLT_CHR，当实际长度为0时，OCIBindByPos()会去除尾随空格。指定实际长度以防止去除尾随空白。对于客户端应用程序不知道其大小的描述符、定位器或引用，请使用指向特定类型的指针的大小；例如，sizeof(OCILobLocator*)。即使模式为OCI_IOV，也同样适用。
indp(IN/OUT)

指向指示符变量或数组的指针。对于所有数据类型，这是指向sb2或sb2值数组的指针。唯一的例外是SQLT_NTY，其中忽略此指针，而指向指示符结构或指示符结构数组的实际指针由OCIBindObject()初始化。对于动态绑定，indp参数被忽略。如果valuep是OUT参数，则必须将indp设置为指向OCI_IND_NULL。
alenp(IN/OUT)

指向数组元素实际长度数组的指针。
- 当使用OCIEnvNlsCreate()时，则alenp长度始终以字节为单位。在SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中，同样的处理方法同样适用于长度前缀。UCS2或NCHAR没有特殊例外。
- 当使用较旧的OCI环境句柄创建接口（OCIEnvCreate()、OCIEnvInit()）时，alenp长度通常以字节为单位。但是只有当字符集为OCI_UC2ID=OCI_UTF16ID或在相应的OCIBind句柄上设置了OCI_ATTR_CHAR_COUNT属性时，alenp长度以字符为单位。对于SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中的长度前缀，同样的处理也适用。
- 对于动态绑定，将忽略此参数。
rcodep(OUT)

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

最大数组长度参数（用户数组可以容纳的最大可能元素数）。仅用于PL/SQL索引表绑定。(暂不支持)
curelep(IN/OUT)

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

指定各种操作模式。有效模式包括：
- OCI_DEFAULT：默认模式。
- OCI_BIND_SOFT：软绑定模式。此模式可提高性能。如果这是第一个绑定，或者某些输入值（如dty或value_sz）与前一个绑定不同，则忽略此模式。如果未执行该语句，则返回错误。如果传递的绑定句柄无效，将导致意外行为。(暂不支持)
- OCI_DATA_AT_EXEC：选择此模式时，value_sz参数定义运行时可以提供的数据的最大大小。应用程序必须随时、多次在数据缓冲区中提供OCI库运行时。运行时数据通过以下方式之一提供：(暂不支持)
- 使用用户定义的函数进行回调，该函数必须在后续调用OCIBindDynamic()时注册。
- 使用OCI提供的调用的轮询机制。如果未定义回调，则假定此模式。
- 当mode设置为OCI_DATA_AT_EXEC时，不要在主调用中提供valuep、indp、alenp和rcodep的值。为indp和alenp传递零（0）。通过使用OCIBindDynamic()注册的回调函数提供值。
- OCI_IOV-绑定数据的非连续地址，valuep参数的类型必须为OCIIOV*。此模式旨在用于分散或聚集绑定，允许将多个缓冲区绑定或定义到一个位置，例如一个缓冲区中前10行的a列、一个缓冲区中接下来的5行，以及另一个缓冲区中剩余的25行。这样就不需要在执行数组执行操作时将所有数据分配并复制到一个大缓冲区中。(暂不支持)

其他说明

无

OCIBindByName

功能描述

在应用程序变量和SQL语句或PL/SQL块中的占位符之间创建关联，通过占位符名称绑定数据。

功能说明

接口信息

OCIBindByName的语法如下：

sword OCIBindByName( OCIStmt       *stmtp, 
                     OCIBind      **bindpp,
                     OCIError      *errhp,
                     const OraText   *placeholder,
                     sb4              placeh_len,
                     void          *valuep,
                     sb4            value_sz,
                     ub2            dty,
                     void          *indp,
                     ub2           *alenp,
                     ub2           *rcodep,
                     ub4            maxarr_len,
                     ub4           *curelep, 
                     ub4            mode );

参数解释如下：

stmtp(IN/OUT)：正在处理的SQL或PL/SQL语句的语句句柄。
bindpp(IN/OUT)：由该调用隐式分配的绑定句柄的地址。绑定句柄维护这个特定输入值的所有绑定信息。当释放语句句柄时，将隐式释放句柄。输入时，指针的值必须为NULL或有效的绑定句柄。
errhp(IN/OUT)：当出现错误时，您可以传递给OCIErrorGet()以获取诊断信息的错误句柄。
placeholder(IN)：由其名称指定的占位符，该占位符映射到与语句句柄关联的语句中的变量。占位符的编码应始终与环境的编码一致。也就是说，如果语句是用UTF-16编写的，那么占位符也是。作为字符串类型参数，占位符应转换为（text*），并以NULL结尾。
placeh_len(IN)：占位符中指定的名称的长度，以字节数为单位，与编码无关。
valuep(IN/OUT)：指向dty参数中指定类型的数据值或数据值数组的指针。
- 当调用了OCIAttrSet()函数将OCI_ATTR_CHARSET_ID设置为OCI_UTF16ID或不推荐使用的OCI_UCS2ID，则该数据可以是UTF-16（以前称为UCS-2）字符串。OCI_UTF16ID是OCI_UCS2ID的新名称。
- 当字符串类型valuep的默认编码是由上一次调用OCIEnvNlsCreate()的charset参数指定的编码，除非调用OCIAttrSet()手动重置绑定句柄的字符集。可以为映射到PL/SQL表或为SQL多行操作提供数据指定数据值数组。
- 当提供一个绑定值数组时，这在OCI术语中称为数组绑定。对于SQLT_NTY或SQLT_REF绑定，valuep参数被忽略。指向OUT缓冲区的指针在由OCIBindObject()初始化的pgvpp参数中设置。
- 当mode设置为OCI_IOV时，传递OCIIOV结构的基址。
value_sz(IN)：此绑定变量的任何数据值（使用valuep传递）的最大可能大小（以字节为单位）。此大小始终应为字节大小。在数组绑定的情况下，这是任何元素可能的最大大小，实际大小在alenp参数中指定。
dty(IN)：要绑定的值的数据类型。
- 当应用程序已在对象模式下初始化时，数据类型（SQLT_NTY）和引用（SQLT_REF）才有效。
- 对于指定数据类型SQLT_CHR，当实际长度为0时，OCIBindByPos()会去除尾随空格。指定实际长度以防止去除尾随空白。对于客户端应用程序不知道其大小的描述符、定位器或引用，请使用指向特定类型的指针的大小；例如，sizeof(OCILobLocator*)。即使模式为OCI_IOV，也同样适用。
indp(IN/OUT)：指向指示符变量或数组的指针。对于所有数据类型，这是指向sb2或sb2值数组的指针。唯一的例外是SQLT_NTY，其中忽略此指针，而指向指示符结构或指示符结构数组的实际指针由- OCIBindObject()初始化。对于动态绑定，indp参数被忽略。如果valuep是OUT参数，则必须将indp设置为指向OCI_IND_NULL。 alenp(IN/OUT)：指向数组元素实际长度数组的指针。
- 当使用OCIEnvNlsCreate()时，则alenp长度始终以字节为单位。在SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中，同样的处理方法同样适用于长度前缀。UCS2或NCHAR没有特殊例外。
- 当使用较旧的OCI环境句柄创建接口（OCIEnvCreate()、OCIEnvInit()）时，alenp长度通常以字节为单位。但是只有当字符集为OCI_UC2ID=OCI_UTF16ID或在相应的OCIBind句柄上设置了OCI_ATTR_CHAR_COUNT属性时，alenp长度以字符为单位。对于SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中的长度前缀，同样的处理也适用。
- 对于动态绑定，将忽略此参数。
rcodep(OUT)：指向列级返回码数组的指针。对于动态绑定，将忽略此参数。
maxarr_len(IN)：最大数组长度参数（用户数组可以容纳的最大可能元素数）。仅用于PL/SQL索引表绑定。
curelep(IN/OUT)：当前数组长度参数（指向执行操作之前或之后数组中实际元素数的指针）。仅用于PL/SQL索引表绑定。
mode(IN)：指定各种操作模式。有效模式包括：
- OCI_DEFAULT-默认模式。
- OCI_BIND_SOFT-软绑定模式。此模式可提高性能。如果这是第一个绑定，或者某些输入值（如dty或value_sz）与前一个绑定不同，则忽略此模式。如果未执行该语句，则返回错误。如果传递的绑定句柄无效，将导致意外行为。（暂不支持）
- OCI_DATA_AT_EXEC-选择此模式时，value_sz参数定义运行时可以提供的数据的最大大小。应用程序必须随时、多次在数据缓冲区中提供OCI库运行时。运行时数据通过以下方式之一提供：（暂不支持）
  - 使用用户定义的函数进行回调，该函数必须在后续调用OCIBindDynamic()时注册。
  - 使用OCI提供的调用的轮询机制。如果未定义回调，则假定此模式。
  - 当mode设置为OCI_DATA_AT_EXEC时，不要在主调用中提供valuep、indp、alenp和rcodep的值。为indp和alenp传递零（0）。通过使用OCIBindDynamic()注册的回调函数提供值。
- OCI_IOV：绑定数据的非连续地址，valuep参数的类型必须为OCIIOV*。此模式旨在用于分散或聚集绑定，允许将多个缓冲区绑定或定义到一个位置，例如一个缓冲区中前10行的a列、一个缓冲区中接下来的5行，以及另一个缓冲区中剩余的25行。这样就不需要在执行数组执行操作时将所有数据分配并复制到一个大缓冲区中。（暂不支持）

其他说明

无

OCIBindArrayOfStruct

功能描述

当通过数据绑定接口OCIBindByName或OCIBindByPos绑定数组数据时，需要设置每次数据的跳过宽度（数组元素宽度），OCIBindArrayOfStruct便是设置静态数组绑定的跳过参数。

功能说明

设置静态数组绑定的跳过参数，跳过的参数都为OCIBindByName或OCIBindByPos中共有的函数包括valuep（数据数组地址）、indp（变量指示符地址）、alenp（数据元素真实长度）、rcodep（列的返回码），分别对应的跳过参数为 OCIBindArrayOfStruct 的pvskip、indskip、alskip、rcskip。

接口信息

OCIBindArrayOfStruct的语法如下：

sword OCIBindArrayOfStruct ( OCIBind     *bindp,
                             OCIError    *errhp,
                             ub4          pvskip, 
                             ub4          indskip, 
                             ub4          alskip, 
                             ub4          rcskip );

参数解释如下：

Bindp（IN/OUT）：绑定句柄。
Errhp（IN/OUT）：当出现错误时，您可以传递给OCIErrorGet()以获取诊断信息的错误句柄。
Pvskip(IN)：跳过下一个数据值的参数，对应valuep参数。（目前只支持统一跳转进行按行按列绑定）
indskip(IN)：跳过下一个指标值或结构的参数，对应indp参数。（目前只支持统一跳转进行按行按列绑定）
alskip(IN)：跳过下一个实际长度值的参数，对应alenp参数。（目前只支持统一跳转进行按行按列绑定）
rcskip(IN)：跳过下一列级别返回代码值的参数，对应rcodep参数。（暂不支持）

其他说明

无

VastbaseG100

数据参数绑定接口

OCIBindByPos

功能描述

功能说明

接口信息

其他说明

OCIBindByName

功能描述

功能说明

接口信息

其他说明

OCIBindArrayOfStruct

功能描述

功能说明

接口信息

其他说明

弹框头部