句柄资源管理接口

DCI句柄资源管理包括DCI句柄管理和DCI描述符管理。

DCI句柄是DCI 库分配的指向存储区域的不透明指针，存储着许多与DCI编程相关的信息，且句柄类型多样，不同句柄存储不同的信息，比如说环境句柄存储着初始的上下文信息，连接句柄存储着数据库连接信息，描述句柄存储着数据信息，错误句柄存储着错误信息等等。

DCI句柄资源管理

DCI句柄资源管理主要包括句柄的分配初始化、句柄属性的获取、句柄的释放，本节主要介绍DCI当中句柄的分配初始化接口和释放功能接口，句柄分配功能是通过DCIHanleAlloc函数实现的，句柄释放则是通过DCIHandleFree函数实现的。

DCI句柄的分类和介绍如下所示：

DCI描述符管理

DCI描述符(有时又叫定位器)是不透明的数据结构，用于维护特定类型数据的信息。比如说用于指示LOB大对象位置的LOB和BFILE定位器、用于存储数据库快照信息的快照描述符等。

DCI描述符管理主要包括描述符的分配和释放，本节主要介绍DCI当中描述符的分配功能接口和释放功能接口，描述符分配功能是通过DCIDescriptorAlloc函数实现的，描述符释放则是通过DCIDescriptorFree函数实现的。

DCI描述符的分类和介绍如下所示：

DCIHandleAlloc

功能描述

该调用用于分配和初始化用户指定类型的句柄。

功能说明

该调用返回指向已分配和初始化的句柄的指针，该句柄对应于用户指定的类型，所有分配的句柄都是基于传入的环境句柄分配的。调用成功时返回DCI_SUCCESS，错误时返回DCI_INVALID_HANDLE，出现错误时没有诊断程序可用。

接口信息

函数/过程

DCIHandleAlloc语法如下：

sword DCIHandleAlloc (
    const void    *parenth,
    void         **hndlpp, 
    ub4            type, 
    size_t         xtramem_sz,
    void         **usrmempp 
);

参数解释如下：

• parenth(IN)：环境句柄。

• Handlpp(OUT)：返回的句柄指针。

• type(IN)：待初始化的句柄类型

• xtramemsz (IN)：指定在分配和初始化句柄期间分配的用户内存量。

• usrmempp (OUT)：返回一个指针，该指针指向xtramemsz大小的用户内存。

外部接口

无。

其它说明

无。

DCIHandleFree

功能描述

释放用户指定的句柄指向的资源。

功能说明

该调用释放指定句柄指向的存储资源，句柄的类型由输入参数type决定。成功返回DCI_SUCCESS，失败返回DCI_INVALID_HANDLE或者DCI_ERROR。调用该函数会显式释放所有类型的句柄，当父句柄被释放之后子句柄也随之释放。当语句句柄被释放，相应的游标只是会断开与该句柄的连接，该游标可能会推迟到下一次连接断开才被关闭。

接口信息

函数/过程

DCIHandleFree语法如下：

sword DCIHandleFree ( 
    DCIEnv    *hndlp,
    ub4        type
    )

具体参数解释如下：

• hndlp：指向待释放的句柄。

• type：句柄类型。

外部接口

无。

其它说明

无。

DCIDescriptorAlloc

功能描述

分配和初始化DCI描述符或者LOB定位器。

功能说明

该调用返回指向DCI描述符或者LOB定位器的指针，类型由用户输入的type参数决定。函数调用成功返回值为DCI_SUCESS，当发生内存不足错误时返回DCI_INVALID_HANDLE。

接口信息

函数/过程

DCIDescriptorAlloc语法如下：

sword DCIDescriptorAlloc (
    const void    *parenth,
    void         **descpp, 
    ub4            type,
    size_t         xtramem_sz,
    void         **usrmempp
);

参数类型解析：

• parenth(IN)：环境句柄。

• descpp(OUT)：返回的描述符指针。

• type(IN)：待初始化的描述类型。

• xtramemsz (IN)：指定在分配和初始化描述符期间分配的用户内存量。

• usrmempp (OUT)：返回一个指针，该指针指向xtramemsz大小的用户内存。

外部接口

无。

其它说明

无。

DCIDescriptorFree

功能描述

释放已经分配的描述符。

功能说明

释放已经分配的描述符，调用成功返回DCI_SUCCESS，调用失败返回DCI_INVALID_HANDLE。所有描述符都会被显式地释放，当环境句柄被释放时也会默认自动释放掉相关的DCI描述符。如果释放的是LOB定位器，需要提前调用DCILobFreeTemporary()接口将临时LOB释放，然后才能调用DCIDescriptor()接口释放该LOB定位器。

接口信息

函数/过程

DCIDescriptorFree语法如下：

sword DCIDescriptorFree ( 
    DCIEnv    *descp,
    ub4        type
    )

具体参数解释如下：

• descp：指向待释放的描述符。

• type：句柄类型。

外部接口

无。

其它说明

无。

DCIDescribeAny

功能描述

描述现有的schema和subschema对象。

功能说明

描述现有的schema和subschema对象。

接口信息

函数/过程

DCIDescriptorFree语法如下：

sword DCIDescribeAny ( DCISvcCtx       *svchp,
            DCIError        *errhp,
            void            *objptr,
            ub4              objptr_len,
            ub1              objptr_typ,
            ub1              info_level,
            ub1              objtyp,
            DCIDescribe     *dschp );

具体参数解释如下：

• Svchp(IN)：服务上下文句柄。

• Errhp(IN/OUT)：当发生错误时，可以传递给 DCIErrorGet()用于诊断信息的错误句柄。

• Objptr(IN)：这个参数可以是：

  1、一个字符串，包含要描述的对象的名称。必须使用以前调用 DCIEnvNlsCreate()的charset参数指定的编码。

  2、指向指向TDO的REF的指针(用于类型)。

  3、指向TDO(用于类型)的指针。

通过为objecptr_typ传递适当的值来区分这些情况。

在情况1中，包含对象名称的字符串应该采用 name1[格式Name2…][@linkname]，例如hr.Employees.employee_id@mydb。数据库链接只允许连接到 Oracle8i 或更高版本的数据库。对象名称由以下SQL规则解释：

• 如果只输入name1并且objectyp等于DCI_PTYPE_SCHEMA，则名称引用已命名的模式。Oracle数据库必须是8.1或更高版本。

• 如果只输入name1并且objectyp等于DCI_PTYPE_DATABASE，那么该名称将引用已命名的数据库。当使用Database_name@db_link_name描述远程数据库时，远程Oracle Database必须在8.1或更高版本中发布。

• 如果只输入了name1，而objectyp不等于DCI_PTYPE_SCHEMA或DCI_PTYPE_DATABASE，那么这个名称将引用当前用户的当前模式中的已命名对象(类型为table、view、process、function、package、type、synonym、order)。当连接到Oracle7服务器时，唯一有效的类型是过程和函数。

• 如果输入name1.name2.name3… ，则对象名称引用名为 name1的模式中的模式或子模式对象。例如，在字符串 hr.loyees.department_id 中，hr是模式的名称，employee是模式中表的名称，department _ id是表中列的名称。

• objnm_len：Objecptr指向的名称字符串的长度。如果传递名称，则必须为非零。如果objecptr是指向TDO或其REF的指针，则可以为零。

• objptr_typ：在objecptr中传递的对象类型。有效值如下：

  • 如果objecptr指向架构对象的名称，则为DCI_OTYPE_NAME（目前只支持此类型）；

  • 如果objecptr是指向指向TDO的REF的指针，则为DCI_OTYPE_REF；

  • 如果objecptr是指向TDO的指针，则为DCI_OTYPE_PTR；

• info_level：为将来的扩展保留。传递DCI_DEFAULT。

• objtyp：所描述的架构对象的类型。有效值如下：

• dschp：调用后用有关对象的描述信息填充的描述句柄。必须是非 NULL 的。

外部接口

无。

其它说明

无。