数据参数绑定接口

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

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

DCIBindByPos

功能描述

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

功能说明

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

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

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

接口信息

函数/过程

DCIBindByPos 的语法如下：

sword DCIBindByPos ( DCIStmt       *stmtp, 
            DCIBind      **bindpp,
            DCIError      *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)：当出现错误时，您可以传递给DCIErrorGet()以获取诊断信息的错误句柄。
position(IN)：占位符属性位置指定。从1开始。
valuep(IN/OUT)：一个数据或数组的地址，类型指定在dty参数中，当提供一个绑定值数组时，这在DCI术语中称为数组绑定。
- 当绑定LOB类型时，缓冲区指针必须是指向DCILobLocator 类型的LOB定位器的指针。给出指针的地址。
- 当绑定SQLT_NTY或SQLT_REF类型时，valuep参数被忽略。指向OUT缓冲区的指针在由DCIBindObject()初始化的pgvpp参数中设置。
- 当DCI_ATTR_CHARSET_ID属性设置为DCI_UTF16ID（替换不推荐使用的DCI_UCS2ID，该属性保留用于向后兼容），则传递给相应绑定调用并使用相应绑定调用接收的所有数据都假定为UTF-16编码。
- 当mode设置为DCI_IOV时，传递DCIIOV结构的基址。
value_sz(IN)：此绑定变量的任何数据值（使用valuep传递）的最大可能大小（以字节为单位）。此大小始终应为字节大小。在数组绑定的情况下，这是任何元素可能的最大大小，实际大小在alenp参数中指定。
dty(IN)：要绑定的值的数据类型。
- 当应用程序已在对象模式下初始化时，数据类型（SQLT_NTY）和引用（SQLT_REF）才有效。
- 对于指定数据类型SQLT_CHR，当实际长度为0时，DCIBindByPos()会去除尾随空格。指定实际长度以防止去除尾随空白。对于客户端应用程序不知道其大小的描述符、定位器或引用，请使用指向特定类型的指针的大小；例如，sizeof(DCILobLocator*)。即使模式为DCI_IOV，也同样适用。
indp(IN/OUT)：指向指示符变量或数组的指针。对于所有数据类型，这是指向sb2或sb2值数组的指针。唯一的例外是SQLT_NTY，其中忽略此指针，而指向指示符结构或指示符结构数组的实际指针由DCIBindObject()初始化。对于动态绑定，indp参数被忽略。如果valuep是OUT参数，则必须将indp设置为指向DCI_IND_NULL。
alenp(IN/OUT)：指向数组元素实际长度数组的指针。
- 当使用DCIEnvNlsCreate()时，则alenp长度始终以字节为单位。在SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中，同样的处理方法同样适用于长度前缀。UCS2或NCHAR没有特殊例外。
- 当使用较旧的DCI环境句柄创建接口（DCIEnvCreate()、DCIEnvInit()）时，alenp长度通常以字节为单位。但是只有当字符集为DCI_UC2ID=DCI_UTF16ID或在相应的DCIBind句柄上设置了DCI_ATTR_CHAR_COUNT属性时，alenp长度以字符为单位。对于SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中的长度前缀，同样的处理也适用。
- 对于动态绑定，将忽略此参数。
rcodep(OUT)：指向列级返回码数组的指针。对于动态绑定，将忽略此参数。
- maxarr_len(IN)：最大数组长度参数（用户数组可以容纳的最大可能元素数）。仅用于PL/SQL索引表绑定。(暂不支持)
curelep(IN/OUT)：当前数组长度参数（指向执行操作之前或之后数组中实际元素数的指针）。仅用于PL/SQL索引表绑定。(暂不支持)
mode(IN)：指定各种操作模式。有效模式包括：
- DCI_DEFAULT-默认模式。
- DCI_BIND_SOFT-软绑定模式。此模式可提高性能。如果这是第一个绑定，或者某些输入值（如dty或value_sz）与前一个绑定不同，则忽略此模式。如果未执行该语句，则返回错误。如果传递的绑定句柄无效，将导致意外行为。(暂不支持)
- DCI_DATA_AT_EXEC-选择此模式时，value_sz参数定义运行时可以提供的数据的最大大小。应用程序必须随时、多次在数据缓冲区中提供DCI库运行时。运行时数据通过以下方式之一提供：(暂不支持)
  - 使用用户定义的函数进行回调，该函数必须在后续调用DCIBindDynamic()时注册。
  - 使用DCI提供的调用的轮询机制。如果未定义回调，则假定此模式。
  - 当mode设置为DCI_DATA_AT_EXEC时，不要在主调用中提供valuep、indp、alenp和rcodep的值。为indp和alenp传递零（0）。通过使用DCIBindDynamic()注册的回调函数提供值。
- DCI_IOV-绑定数据的非连续地址，valuep参数的类型必须为DCIIOV*。此模式旨在用于分散或聚集绑定，允许将多个缓冲区绑定或定义到一个位置，例如一个缓冲区中前10行的a列、一个缓冲区中接下来的5行，以及另一个缓冲区中剩余的25行。这样就不需要在执行数组执行操作时将所有数据分配并复制到一个大缓冲区中。(暂不支持)

外部接口

无。

其它说明

无。

DCIBindByName

功能描述

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

功能说明

接口信息

函数/过程

DCIBindByName的语法如下：

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

外部接口

无。

其它说明

无。

DCIBindArrayOfStruct

功能描述

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

功能说明

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

接口信息

函数/过程

DCIBindArrayOfStruct的语法如下：

sword DCIBindArrayOfStruct ( DCIBind     *bindp,
            DCIError    *errhp,
            ub4          pvskip, 
            ub4          indskip, 
            ub4          alskip, 
            ub4          rcskip );

参数解释如下：

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

外部接口

无。

其它说明

无。

DCIBindDynamic

功能描述

注册用于动态数据分配的用户回调。

功能说明

注册用于动态数据分配的用户回调。

接口信息

函数/过程

语法如下：

DCIBindDynamic(DCIBind  *bindp, DCIError  *errhp,  void  *ictxp,
        DCICallbackInBind icbfp, void *octxp,
        DCICallbackOutBind ocbfp) ;

参数说明：

输入
- bindp(IN/OUT): 调用 DCIBindByName () 或DCIBindByPos () 返回的绑定句柄。
- errhp(IN/OUT): 一个错误句柄，当出现错误时，可以传递给 DCIErrorGet () 以获取诊断信息。
- ictxp(IN): 回调函数 icbfp 所需的上下文指针。
- icbfp(IN): 在运行时返回指向 IN 绑定值或段的指针的回调函数。
- octxp(IN): 回调函数 ocbfp () 所需的上下文指针。
- ocbfp(IN): 在运行时返回指向 OUT 绑定值或段的指针的回调函数。
输出
sword(OUT)：函数是否成功执行。

DCICallbackInBind 回调函数

DCICallbackInBind   (icbfp)(
void  *ictxp,
DCIBind   *bindp,
ub4     iter,
ub4    index,
void   **bufpp,
ub4   *alenpp,
ub1  *piecep,
void  **indpp );

输入
- ictxp(IN/OUT): 此回调函数的上下文指针。
- bindp(IN): 传入以唯一标识此绑定变量的绑定句柄。
- iter(IN): 从0 开始的执行选代值。(当前写死)
- index(IN): 当前数组的索引，用于 PL/SQL 中的数组绑定。对于SQL，它是行索引。该值从0 开始，并且不大于绑定调用的 curelep 参数。(当前写死)
- bufpp(IN): 指向缓冲区或存储的指针。对于描述符，*bufpp 包含指向描述符的指针。例如，如果定义以下参数，则将 *bufpp 设置为 lobp，而不是*lobp。
- alenp(IN): 指向存储的指针，DCI 用于在读取绑定值或片段后填允绑定值或片段的大小。对于描述符，将指针的大小传递给描述符;例如，sizeof (DCILobLocator *)。
- piecep(IN): 绑定值的一部分。这可以是以下值之一: DCI_ONE_PIECE、DCI_FIRST_PIECE、DCI_NEXT_PIECE和 DCI_LAST_PIECE。对于不支持分段操作的数据类型，必须传递DCI_ONE_PIECE否则将生成错误。
- indpp(IN): 包含指示器值。这是指向 sb2 值的指针或指向用于绑定命名数据类型的指示器结构的指针。
输出
- sb4 (OUT): 函数成功返回 CONTINUE。

DCICallbackOutBind 回调函数

DCICallbackOutBind   (ocbfp)(
void     *octxp,
DCIBind   *bindp,
ub4     iter,
ub4    index,
void   **bufpp,
ub4   *alenpp,
ub1  *piecep,
void  **indpp 
ub2   **rcodepp);

输入：
- octxp(IN/OUT): 此回调函数的上下文指针。
- bindp(IN): 传入以唯一标识此绑定变量的绑定句柄。
- iter(IN): 从0 开始的执行选代值。
- index(IN): 对于 PL/SQL，为绑定数组的当前数组的索引。对于 SOL，索引是当前达代中的行号。它从 0 开始，并且不得大于绑定调用的 curelep 参数。(当前写死)
- bufpp(OUT): 指向用于写入绑定值或片段的缓冲区的指针。
- alenpp(IN/OUT): 指向存储的指针，DCI用于在读取绑定值或片段后填充绑定值或片段的大小。它以字节为单位。
- piecep(IN/OUT): 将回调(应用程序)中的片段值返回到 Oracle 数据库，如下所示:
  - IN-该值可以是 DCI_ONE_PIECE或 DCI_NEXT_PIECE。
  - OUT-取决于IN 值:
    - 如果IN 值为 DCI_ONE_PIECE，则可以 DCI_ONE_PIECE或 DCI_FIRST_PIECE OUT值。
    - 如果IN值为 DCI_NEXT_PIECE，则可以 DCI_NEXT_PIECE或 DCI_LAST_PIECE OUT值。
- indpp(OUT): 包含指示器值。这是指向 sb2 值的指针，或指向用于绑定命名数据类型的指示器结构的指针。
- recodepp(OUT): 返回指向返回代码的指针。
输出
- sb4(OUT): 函数成功返回CONTINUE。

外部接口

无。

其它说明

无。

VastbaseG100

数据参数绑定接口

DCIBindByPos

功能描述

功能说明

接口信息

其它说明

DCIBindByName

功能描述

功能说明

接口信息

其它说明

DCIBindArrayOfStruct

功能描述

功能说明

接口信息

其它说明

DCIBindDynamic

功能描述

功能说明

接口信息

其它说明

弹框头部