句柄资源管理接口

OCIHandleAlloc

功能描述

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

功能说明

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

接口信息

OCIHandleAlloc语法如下：

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

参数解释如下：

• parenth(IN)：环境句柄
• Handlpp(OUT)：返回的句柄指针
• type(IN)：待初始化的句柄类型
• xtramemsz (IN)：指定在分配和初始化句柄期间分配的用户内存量。
• usrmempp (OUT)：返回一个指针，该指针指向xtramemsz大小的用户内存。

其他说明

无

OCIHandleFree

功能描述

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

功能说明

该调用释放指定句柄指向的存储资源，句柄的类型由输入参数type决定。成功返回OCI_SUCCESS，失败返回OCI_INVALID_HANDLE或者OCI_ERROR。

调用该函数会显式释放所有类型的句柄，当父句柄被释放之后子句柄也随之释放。 当语句句柄被释放，相应的游标只是会断开与该句柄的连接，该游标可能会推迟到下一次连接断开才被关闭。

接口信息

函数/过程

OCIHandleFree语法如下：

sword OCIHandleFree ( 
OCIEnv    *hndlp,
    ub4        type
    )

具体参数解释如下：

• hndlp：指向待释放的句柄
• type：句柄类型

其他说明

无

OCIDescriptorAlloc

功能描述

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

功能说明

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

接口信息

函数/过程

OCIDescriptorAlloc语法如下：

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

参数类型解析：

• parenth(IN)：环境句柄。
• descpp(OUT)：返回的描述符指针。
• type(IN)：待初始化的描述类型。
• xtramemsz (IN)：指定在分配和初始化描述符期间分配的用户内存量。
• usrmempp (OUT)：返回一个指针，该指针指向xtramemsz大小的用户内存。

其他说明

无

OCIDescriptorFree

功能描述

释放已经分配的描述符。

功能说明

释放已经分配的描述符，调用成功返回OCI_SUCCESS，调用失败返回OCI_INVALID_HANDLE。所有描述符都会被显式地释放，当环境句柄被释放时也会默认自动释放掉相关的OCI描述符。

如果释放的是LOB定位器，需要提前调用OCILobFreeTemporary()接口将临时LOB释放，然后才能调用OCIDescriptor()接口释放该LOB定位器。

接口信息

函数/过程

OCIDescriptorFree语法如下：

sword OCIDescriptorFree ( 
OCIEnv    *descp,
    ub4        type
    )

具体参数解释如下：

• descp：指向待释放的描述符
• type：句柄类型

其他说明

无

OCIDescribeAny

功能描述

描述现有的schema和subschema对象。

功能说明

描述现有的schema和subschema对象。

接口信息

函数/过程

OCIDescriptorFree语法如下：

sword OCIDescribeAny ( OCISvcCtx       *svchp,
                       OCIError        *errhp,
                       void            *objptr,
                       ub4              objptr_len,
                       ub1              objptr_typ,
                       ub1              info_level,
                       ub1              objtyp,
                       OCIDescribe     *dschp );

具体参数解释如下：

• Svchp(IN)：服务上下文句柄
• Errhp(IN/OUT)：当发生错误时，可以传递给 OCIErrorGet ()用于诊断信息的错误句柄。
• Objptr(IN)：这个参数可以是:
  • 一个字符串，包含要描述的对象的名称。必须使用以前调用 OCIEnvNlsCreate ()的 charset 参数指定的编码。
  • 指向指向 TDO 的 REF 的指针(用于类型)。
  • 指向 TDO (用于类型)的指针。 通过为 objecptr _ typ 传递适当的值来区分这些情况。 在情况1中，包含对象名称的字符串应该采用 name1[格式。Name2… ][@linkname ] ，例如 hr.Employees.employee _ id@mydb。数据库链接只允许连接到 Oracle8i 或更高版本的数据库。对象名称由以下 SQL 规则解释:
    • 如果只输入 name1并且 objectyp 等于 OCI _ PTYPE _ SCHEMA，则名称引用已命名的模式。Oracle 数据库必须是8.1或更高版本。
    • 如果只输入 name1并且 objectyp 等于 OCI _ PTYPE _ DATABASE，那么该名称将引用已命名的数据库。当使用 Database _ name@db _ link _ name 描述远程数据库时，远程 Oracle Database 必须在8.1或更高版本中发布。
    • 如果只输入了 name1，而 objectyp 不等于 OCI _ PTYPE _ SCHEMA 或 OCI _ 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 指向架构对象的名称，则为 OCI _ OTYPE _ NAME（目前只支持此类型）
  • 如果 objecptr 是指向指向 TDO 的 REF 的指针，则为 OCI _ OTYPE _ REF
  • 如果 objecptr 是指向 TDO 的指针，则为 OCI _ OTYPE _ PTR
• info_level：为将来的扩展保留。传递 OCI _ DEFAULT。
• objtyp：所描述的架构对象的类型。有效值如下:
  • OCI_PTYPE_TABLE, for tables（目前只支持此类型）
  • OCI_PTYPE_VIEW, for views
  • OCI_PTYPE_PROC, for procedures
  • OCI_PTYPE_FUNC, for functions
  • OCI_PTYPE_PKG, for packages
  • OCI_PTYPE_TYPE, for types
  • OCI_PTYPE_SYN, for synonyms
  • OCI_PTYPE_SEQ, for sequences
  • OCI_PTYPE_SCHEMA, for schemas
  • OCI_PTYPE_DATABASE, for databases
  • OCI_PTYPE_UNK, for unknown schema objects

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

提示信息

正确场景和函数调用提示一样，错误场景通过OCIErrorGet获取报错提示。