logo - 跳到首页

VastbaseG100

基于openGauss内核开发的企业级关系型数据库。

Menu

结果集定义接口

DCIDefineByPos

功能描述

当查询语句将数据从数据库返回到应用程序，必须为select列表中的每个项定义一个输出变量或一个输出变量数组，以便检索数据。DCIDefineByPos将select列表项与类型和输出数据缓冲区相关联，用于接收从数据库检索到的数据。

功能说明

在将select列表项与类型和输出数据缓冲区相关联时，确定返回的结果存储在何处以及以何种格式存储。如果*defnpp为空指针，此调用还隐式地为select列表项分配定义句柄；如果*defnpp中为非空指针，则DCI假定该指针指向一个有效的句柄，该句柄之前已通过调用DCIHandleAlloc()或DCIDefineByPos()分配，这样它就可以在多次获取时重用同一个define句柄。

接口信息

函数/过程

DCIDefineByPos 的语法如下：

sword DCIDefineByPos ( DCIStmt     *stmtp, 
            DCIDefine  **defnpp,
            DCIError    *errhp,
            ub4          position,
            void        *valuep,
            sb4          value_sz,
            ub2          dty,
            void        *indp,
            ub2         *rlenp,
            ub2         *rcodep,
            ub4          mode );

参数解释如下：

  • stmtp(IN/OUT)：请求的SQL查询操作的语句句柄。

  • defnpp(IN/OUT)：指向Define句柄的指针。如果为NULL，则隐式分配define句柄；也可以在此参数中传递非NULL句柄。

  • errhp(IN/OUT)：输出参数，当出现错误时，您可以传递给DCIErrorGet()以获取诊断信息的错误句柄。

  • position(IN)：此值在选择列表中的位置，以1为基础从左到右编号。

  • valuep(IN/OUT)：指向dty参数中指定类型的缓冲区或缓冲区数组的指针。

    • 当一次提取调用中需要多行的结果时，可以指定多个缓冲区。对于LOB，缓冲区指针必须是指向DCILobLocator类型的LOB定位器的指针。给出指针的地址。

    • 当mode设置为DCI_IOV时，传递DCIIOV结构的基址。(暂不支持)

  • value_sz(IN)： 每个valuep缓冲区的大小（字节）。如果数据以VARCHAR2格式存储在内部，则所需的字符数（如果不同于以字节为单位的缓冲区大小）可以使用OCIAttrSet()指定。在多字节转换环境中，如果指定的字节数不足以处理所需的字符数，则会生成截断错误。如果将DCI_ATTR_CHARSET_ID属性设置为DCI_UTF16ID（替换不推荐使用的DCI_UCS2ID，该属性保留用于向后兼容），则传递给相应定义调用并使用相应定义调用接收的所有数据都假定为UTF-16编码。

    • 当mode设置为DCI_IOV时，传递数据值的大小。(暂不支持)

  • dty(IN)：valuep参数的数据类型。

    • 当数据类型（SQLT_NTY）和REF（SQLT_REF）时仅在环境初始化的对象模式下有效。SQLT_CHR和SQLT_LNG可以指定为CLOB列，SQLT_BIN和SQLT_LBI可以指定BLOB列。

  • indp(IN)： 指向指示符变量或数组的指针。为标量数据类型，指向sb2或sb2数组的指针。忽略SQLT_NTY定义。对于SQLT_NTY指向数据类型指示符结构或数据类型指示符结构数组的指针，由后续的DCIDefineObject()调用关联。

  • rlenp(IN/OUT)：指向数据长度数组的指针。

    • 当使用DCIEnvNlsCreate()时，则rlenp长度以字节为单位。在SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中，同样的处理方法同样适用于长度前缀。UCS2或NCHAR没有特殊例外。

    • 当使用较旧的DCI环境句柄创建接口（DCIEnvCreate()、DCIEnvInit()）时，rlenp长度通常以字节为单位。但是当字符集为DCI_UC2ID=DCI_UTF16ID或在相应的DCIBind句柄上设置了DCI_ATTR_CHAR_COUNT属性时，rlenp长度以字符为单位。对于SQLT_VCS（2字节长度前缀）和SQLT_LVC（4字节长度前缀）类型中的长度前缀，同样的处理也适用。

  • rcodep(OUT)： 指向列返回码数组的指针。

  • mode(IN) ：有效模式包括：

    • DCI_DEFAULT-默认模式。

    • DCI_DEFINE_SOFT-此模式可提高通话性能。如果这是第一次定义，或者某些输入参数（如dty或value_sz）与之前的定义不同，则忽略此模式。如果传递了无效的定义句柄，则会出现意外行为。如果未执行该语句，则返回错误。(暂不支持)

    • DCI_DYNAMIC_FETCH-对于需要在获取时动态分配数据的应用程序，必须使用此模式。可以使用DCIDefineDynamic()调用定义回调。value_sz参数定义在运行时提供的数据的最大大小。当客户端库需要一个缓冲区来返回提取的数据时，会调用回调来提供一个运行时缓冲区，将一部分或所有数据返回到该缓冲区。(暂不支持)

    • DCI_IOV-定义数据的非连续地址。valuep参数的类型必须为DCIIOV*。此模式旨在用于分散或聚集绑定，允许将多个缓冲区绑定或定义到一个位置，例如一个缓冲区中前10行的a列、一个缓冲区中接下来的5行，以及另一个缓冲区中剩余的25行。这样就不需要在执行数组执行操作时将所有数据分配并复制到一个大缓冲区中。(暂不支持)

外部接口

无。

其它说明

无。

DCIDefineArrayOfStruct

功能描述

指定静态数组定义所需的其它属性，用于结构数组（多行、多列）获取。

功能说明

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

接口信息

函数/过程

DCIDefineArrayOfStruct 的语法如下：

sword DCIDefineArrayOfStruct ( DCIDefine   *defnp,
                DCIError    *errhp,
                ub4          pvskip, 
                ub4          indskip, 
                ub4          rlskip,
                ub4          rcskip );

参数解释如下：

  • defnp(IN/OUT)： 通过调用DCIDefineByPos()返回的define结构的句柄。

  • errhp(IN/OUT)： 当出现错误时，您可以传递给DCIErrorGet()以获取诊断信息的错误句柄。

  • Pvskip(IN)：跳过下一个数据值的参数，对应valuep参数。（目前只支持统一跳转进行按行按列绑定）

  • indskip(IN)： 跳过下一个指标值或结构的参数，对应indp参数。（目前只支持统一跳转进行按行按列绑定）

  • alskip(IN)： 跳过下一个实际长度值的参数，对应alenp参数。（目前只支持统一跳转进行按行按列绑定）

  • rcskip(IN)：跳过下一列级别返回代码值的参数，对应rcodep参数。(暂不支持)

外部接口

无。

其它说明

无。