人大金仓数据库KingbaseES——客户端编程接口OCI简介

关键字：

KingbaseES、客户端编程接口、OCI

1.KES客户端接口概述

数据库接口是主要指访问数据库的编程接口，通常由数据库供应商或者第三方组织提供，是连接客户端应用程序和数据库系统的桥梁，能够为应用开发人员提供众多的开发生态支持。同其他主流数据库一样，KES也提供了丰富的接口和开发框架支持，用以支持KES数据库丰富的数据类型和特性，提供包括各种语言的标准接口，ORM框架方言包，Oracle生态接口，PG生态接口等等，无论是新应用开发还是存量应用迁移，都能最大限度的满足需要。在具备数据库接口的通用能力（连接管理、语句管理、结果集管理、数据类型转换、错误处理、多线程安全等）之外，KES还额外推出了批量导入COPY和流复制两种功能，使其能应对更多的应用场景。

KES客户端编程接口支持ODBC、JDBC、DCI、Perl DBI、Gokb、PHP PDO、Nodejs、Python、ado.net标准接口函数，其层次关系如图1所示。此外，KES还支持Hibernate、MyBatis、Qt、Activiti、Entity Framework等多种开发框架，具备强大的应用开发和迁移能力。

图1 KES客户端编程接口层次关系

2.OCI接口与相关概念

OCI、Pro*C与OCCI是三类典型的Oracle生态C类接口，其中ORACLE调用接口（Oracle Call Interface，OCI）是最全面、性能最高、应用最为广泛的基于原生“C”语言的 Oracle 数据库接口，支持C和C++的数据类型、调用、语法和语义。作为 Oracle 数据库的原生接口，OCI接口不仅提供 Oracle 数据库的全部功能，还对 Oracle 数据库核心内部发出的查询、语句和调用进行了增强。

OCI接口中有一个重要的概念——句柄。几乎每一个OCI函数的参数列表中都含有一个或者多个句柄，指向OCI库分配的保存着上下文信息、连接信息、错误信息或者关于SQL及PLSQL的绑定信息的存储区域的不透明指针。不仅能够减少对全局变量的需要，也使错误报告更加容易。OCI定义了众多句柄，其中最常用的句柄有环境句柄（Environment Handle）、错误句柄（Error Handle）、服务上下文句柄（Service Context Handle）、语句句柄（Statement Handle）、服务器句柄（Server Handle）、会话句柄（Session Handle）、线程句柄（Thread Handle）等，其关系如图2所示。

图2 OCI句柄及其关系

除了绑定、定义和线程句柄之外，其他句柄的分配都是针对一个特定的环境句柄来说的，在执行分配句柄的调用时，需要将环境句柄作为参数之一传入。就此而言，环境句柄是其他句柄的父句柄，作为OCIHandleAlloc()函数的parent参数来分配其他句柄类型。每一个环境句柄都包含一个支持快速访问的内存缓存，所有环境句柄下的内存分配都通过该缓存完成。绑定句柄和定义句柄是特定于语句句柄分配的，在执行具体的SQL语句的时候被隐含创建并连接到语句句柄上，也随之隐含释放。

句柄本质上是一个指针，因此在使用之后必须通过OCIHandleFree()进行释放。当一个父句柄释放之后，所有与其关联的子句柄都将一并释放且不能再使用。

DCI 是 KES 提供的应用程序编程接口，该接口兼容 OCI 的功能，允许应用程序使用函数调用来访问KingbaseES 数据库，并控制 SQL 语句执行和数据访问的所有阶段。

3.OCI编程的一般流程

OCI程序实质上是第三代程序设计语言（如C、C++、COBOL 与 FORTRAN等）对OCI子函数库的调用，其主要过程分为环境初始化与句柄生成、连接数据库、执行事务与结果处理、释放句柄。其中初始化句柄和建立数据库连接的主要流程如图3所示。

图3 OCI句柄初始化与连接数据库过程

上述过程中，创建OCI环境和分配环境句柄主要通过OCIEnvCreate()来实现，错误句柄、服务上下文句柄、语句句柄、服务器句柄和会话句柄的创建没有严格的先后顺序。

初始化服务器句柄是创建数据库服务的访问路径，提供执行SQL或者PLSQL语句的环境。有两种方式，一种是多会话、多连接的OCIServerAttach()，主要用于应用程序对单一数据库连接需要维护多个用户会话。另外一种是单会话，单连接的OCILogon()，适用于应用程序对某一数据库连接，仅支持单用户进程，使用OCILogon()函数初始化会话和认证的应用程序必须调用OCILogoff()来终止。

OCISessionBegin()是为用户创建到特定数据库的会话，要建立两个不可相互替代的会话，就必须指定一个相同的服务上下文句柄和一个新的会话上下文句柄，若是使用新的服务上下文句柄和会话上下文句柄会导致前一个用户退出，并引发错误。

OCI连接有两种方式，分别为Blocking（阻塞）和non_Blocking（非阻塞），阻塞模式下，调用OCI操作时，必须等到OCI操作完成之后服务器才会将信息反馈给客户端，非阻塞模式下，客户端一旦将OCI操作交给服务器，服务器会立刻返回OCI_STILL_EXECUTING信息，并不等待服务端操作完成，因此需要应用程序对该返回信息进行判断，已确定执行是否成功。阻塞和非阻塞模式可通过设置服务器属性OCI_ATTR_NONBLOCKING_MODE设定，系统默认为阻塞模式。

在连接好数据库之后，即可执行SQL语句，SQL语句的执行过程如图4所示。

SQL中的定义语句（如CREATE，DROP）和控制语句（如GRANT，EVOKE），由于没有数据的输入输出，只需要图4中的第一步和第三步即可；

操作语句（如INSERT，DELETE，UPDATE）则需要执行前三步；

查询语句（如SELECT）不仅可能有数据输入，而且也有数据的输出，因此需要依次执行六个步骤。

在SQL语句执行完之后，需要调用OCISessionEnd()删除用户会话、调用OCIServerDetach()删除对数据源的访问，调用OCIHandleFree()释放每一个句柄。

图4 SQL语句执行与会话释放过程

更多信息，参见https://help.kingbase.com.cn/v8/index.html