OCI基础部分内容包含以下几部分内容：

在Linux和UNIX系统中进行OCI和OCCI客户端程序开发所需要用到的OCI和OCCI头文件在$ORACLE_HOME/rdbms/public路径下。无论是Oracle数据库服务器安装还是Oracle管理或用户客户端安装，这些文件都是可用的。 所有示例程序以及其相关的头文件在$ORACLE_HOME/rdbms/public目录下。这些示例程序只能从Examples介质中安装。

Examples 11gr2的Examples安装包为linux_11gR2_examples.zip，从官网下载，并按照Oracle Database Examples Installation Guide中的安装包步骤进行安装即可。 关于Examples中的样例程序和各自的目的说明会在单独一个笔记中阐述。

demo路径下提供了若干makefiles文件，每个makefiles都包含注释来描述使用它编译可执行文件的使用方法说明。Oracle建议如果允许的话使用这些示例的makefile文件，以避免编译和连接过程中的错误。

demo路径下的demo_rdbms.mk文件是一个示例的makefile文件。阅读注释可知如何构建OCI样例程序。确保你自己定制的makefile文件中在INCLUDE路径信息中包含$ORACLE_HOME/rdbms/public路径。 ociucb.mk文件是一个构建调用共享库的样例makedile。

OCI 应用程序的总体目标是代表多个用户进行操作。 在 n 层配置中，多个用户向客户端应用程序发送 HTTP 请求。 客户端应用程序可能需要执行一些数据操作，包括交换数据和进行数据处理。 OCI使用下面的工作流：

句柄和描述符是OCI应用中经常用到的不透明数据结构。它们可用通过调用特殊分配函数被直接分配，也可以通过OCI函数隐式地进行分配。 句柄和描述符存储与数据、连接或应用程序行为有关的信息。 下一节将更详细地定义句柄。

几乎每个OCI调用的参数列表中都会包含一个或多个句柄。一个句柄就是一个指向由OCI库分配的存储空间的不透明指针。应用可以使用句柄存储上下文或连接信息，例如环境或服务上下文句柄，也可以存储OCI函数或数据的信息，例如错误或describe句柄。句柄让编程变得简单，因为是使用库来维护数据而非应用来维护数据。 大多数OCI应用必须要获取存储在句柄中的信息，所以设计通过set和get属性的OCI调用，OCIAttrGet()和OCIAttrSet()来访问或设置这些信息。 下表列出了OCI中的各类句柄，每种句柄类型对应的C数据类型以及在OCI调用中标识句柄类型的常量表示

除了绑定、定义、线程句柄之外，其他句柄的分配都是针对一个特定环境句柄来说的。在执行分配句柄的调用时，需要将环境句柄作为参数之一传入，因此分配的句柄是特定于一个环境的。 绑定和定义句柄是特定于语句句柄分配的，其中包含语句句柄所代表的语句的一些信息。 绑定和定义局部由OCI库隐式地分配，不需要用户分配。 环境句柄由OCIEnvCreate()或OCIEnvNlsCreate()的调用完成分配和初始化。任何一个OCI应用都需要用到这两个函数中的一个。 所有用户分配的句柄的初始化都通过调用OCI句柄分配函数OCIHandleAlloc()来完成。 句柄的类型包括：会话池句柄，直接路径上下文句柄，线程句柄，COR句柄，订阅句柄，描述句柄，语句句柄，服务上下文句柄，错误句柄，服务器句柄，连接池句柄，HA事件句柄，管理句柄。 线程句柄通过OCIThreadHndInit()调用进行分配。 所有应用必须释放不再使用的句柄，释放句柄的通过OCIHandleFree()完成。

注意： 当一个母句柄释放，所有与其关联的子句柄都将一并释放并且不能再被使用。例如一个语句句柄被释放后，任何与其相关的绑定句柄和定义句柄都会一并释放。

句柄减少了对全局变量的需求，同时简化了错误报告，可以使用一个错误句柄来返回错误和诊断信息。

环境句柄定义了一个包含所有OCI函数的上下文。每个环境句柄包含一个允许快速内存访问的内存缓存区域。所有在该环境句柄下的内存分配都是从缓存区域分配的。如果多个线程试图在同一个环境句柄下分配内存，则对缓存区域的访问是序列化的。当多个线程共享一个环境句柄时，在访问缓存时可能会发生阻塞。 除绑定和定义句柄是隐式分配的，其他句柄的分配在调用OCIHandleAlloc()函数时将环境句柄作为母句柄参数传入。

大多数OCI调用中会将错误句柄作为一个参数。错误句柄维护OCI操作期间发生的错误信息。如果一个调用过程中发生错误，可以将错误句柄传递给OCIErrorGet()来获取更多错误发生时的相关信息。 分配错误句柄时在一个OCI应用中第一步需要完成的内容之一，因为大多数OCI调用需要使用一个错误句柄做参数。

服务上下文句柄定义了确定 OCI 调用服务器的操作上下文的属性。 服务上下文句柄包含三个句柄作为其属性，分别代表服务器连接、用户会话和事务。句柄之间的关系如下图描述： 服务器句柄标识一个到数据库的连接。它通过面向连接的传输机制转换为一个物理连接。 用户会话句柄定义了一个用户的角色和权限(或者说，用户安全域)，以及调用执行的操作上下文。 事务句柄定义了执行SQL操作的事务。事务上下文包含用户会话状态信息，涉及任何获取状态和包实例化等。 将服务上下文句柄以这样的方式拆分成3个句柄，可以提升应用扩展能力，并且使得程序员可以创建复杂的多层应用程序和事务处理 (TP) 监视器，以代表多应用程序服务器和不同事务上下文上的多个用户执行请求。 在使用服务上下文之前，必须先通过OCIHandleAlloc(),OCILogon()或OCILogon2()分配并初始化服务上下文。服务上下文可以通过OCIHandleAlloc()显式分配并通过OCIAttrSet()使用服务器句柄，用户会话句柄和事务句柄进行初始化。如果服务上下文是通过LOCLogon()隐式分配的，那么同时也隐式地完成了初始化。 如果应用程序在任何时候，都只需为每个数据库连接维护一个单一地用户会话，那么可以调用OCILogon()来获取一个已经初始化地服务上下文句柄。 如果应用程序需要更复杂地会话管理，则需要显式地分配服务上下文句柄，并且必须将服务器句柄和用户会话句柄显式设置到服务上下文句柄中。OCIServerAttach() 和 OCISessionBegin() 调用分别初始化服务器和用户会话句柄。 应用程序仅在全局事务或有多个会话活动的事务时才显式定义事务。其他情况下应用程序对数据库进行更改时，可以使用OCI自动创建的隐式事务。

语句句柄是标识一个SQL或PL/SQL语句及其相关连属性的上下文。 输入和输出绑定变量的信息存储在绑定句柄中。OCI 库为每个使用 OCIBindByName() 或 OCIBindByPos() 函数绑定的占位符分配一个绑定句柄。 用户禁止自行分配绑定句柄，绑定句柄由绑定调用隐式地分配。 由一个查询语句返回的数据，在获取时依赖定义句柄的规范进行转换和检索。OCI 库为每个由 OCIDefineByPos() 定义的输出变量分配一个定义句柄。用户禁止自行分配定义句柄，定义句柄由定义调用隐式地分配。 绑定句柄和定义句柄由 OCI 库隐式分配，并且在重复绑定或定义操作时透明地被重用。 对于第 5 章中描述的高级绑定或定义操作，应用程序需要绑定句柄或定义句柄的实际值。当语句句柄被释放或者在语句句柄上prepare新语句时，绑定句柄和定义句柄被释放。 显式地分配绑定句柄或定义句柄可能会导致内存泄漏。 显式地释放绑定句柄或定义句柄可能会导致程序异常终止。

描述符句柄在OCI描述函数OCIDescribeAny()调用时使用。这个调用函数用于获取数据库中schema对象相关信息(例如，函数或存储过程)。这个调用使用一个描述句柄作为一个参数，同时传入被描述的对象信息。调用完成后，描述句柄被对象信息所填充。届时OCI应用程序可以通过参数描述符的属性获取描述信息。

一些处理 Oracle 数据库中对象的 OCI 应用程序使用复杂对象检索 (COR) 句柄。 此句柄包含 COR 描述符，这些描述符提供用于检索被其他对象引用的对象的指示。

线程句柄在多线程环境中使用，更多信息参阅OCITthreadPackage。

订阅句柄由注册和订阅接收数据库事件通知或 AQ 命名空间事件通知的 OCI 客户端应用程序使用。订阅句柄封装了所有与客户注册相关的信息。

对于使用 Oracle 数据库直接路径加载引擎的 OCI 应用程序，直接路径句柄是必需的。 直接路径加载接口使得应用程序能够访问 Oracle 数据库的直接块格式化程序。下图显示了不同种类的直接路径句柄。

连接池句柄用于通过调用特定 OCI 函数将物理连接池化为虚拟连接的应用程序。

所有OCI句柄都有代表其中存储的数据的属性。用户可以通过调用获取属性的函数OCIAttrGet()来读取句柄属性，通过调用设置属性的函数OCIAttrSet()来修改句柄属性。 例如，下面例子中通过写入OCI_ATTR_USERNAME属性来设置会话句柄的用户名。

有些OCI函数在调用前，需要先设置好特定的句柄属性。例如，当调用OCISessionBegin()建立一个用户登录会话时，在调用前用户会话句柄上必须设置好用户名和密码。 其他OCI函数则在调用完成后返回有用的数据到句柄属性中。例如，当调用OCIStmtExecute()执行一个SQL查询时，与select列表相关联的描述信息被返回到语句句柄中，如下所示。

OCI描述符和定位符是维护特定数据信息的不透明数据结构。下表列出描述符和定位符类型以及其对应的C数据类型和调用OCIDescriptorAlloc()分配描述符时指定类型用的OCI类型常量。释放描述符和定位符使用OCIDescriptorFree()函数。

注意： 尽管对于LOB类型只有一个C数据类型OCILobLocator，但是内部LOB类型和外部LOB类型在分配定位符的时候指定的OCI类型常量是不同的。

每种描述符的主要作用如下，后续做详细描述 OCISnapshot——语句执行中使用 OCILobLocator——用于LOB(OCI_DTYPE_LOB)或者BFILE(OCI_DTYPE_FILE)调用 OCIParam——用于描述相关调用 OCIRowid——用于绑定或定义ROWID值 OCIDateTime和OCIInterval——用于日期和间隔类型 OCIComplexObjectComp——用于复杂对象检索 OCIAQEnqOptions,OCIAQDeqOptions,OCIAQMsgProperties,OCIAgent——用于高级队列 OCIAQNotify——用于发布订阅通知 OCIServerDNs——用于发布基于LDAP的订阅通知

在调用执行语句函数OCIStmsExecute()时，快照描述符是一个可选参数。它表示一个查询在代表数据库某个事件状态的快照中执行。 通过调用OCIDescriptorAlloc()时传入OCI_DTYPE_SNAP作为类型参数分配快照描述符。

大对象(LOB)类型是一种可以存储二进制大对象或字符大对象的Oracle数据类型。在数据库中，一个数据行的LOB列中或者一个对象的LOB属性中，存储的是一个叫做LOB定位符的不透明数据结构。定位符可以理解为是一个指向独立存储在另一个位置的真正LOB数据的指针。

注意： 用户可以根据应用来选择用或不用LOB定位符。用户也可以使用不需要指定LOB定位符的LOB数据接口。在数据接口中用户可以为CLOB类型绑定或定义字符数据，为BLOB绑定或定义RAW数据。

OCILOB定位符用于在LOB(BLOB或CLOB)或FILE(BFILE)上指向OCI操作。OCILobXXX函数使用LOB定位符而非LOB值做参数。OCILOB函数不使用LOB数据作为参数，它们使用LOB定位符做参数并操作定位符指向的LOB数据。 通过调用OCIDescriptorAlloc()函数并传入OCI_DTYPE_LOB作为类型参数来为BLOB或CLOB数据分配LOB定位符，通过传入OCI_DTYPE_FILE作为类型参数来为BFILE数据分配LOB定位符。

注意： 两种LOB定位符不能内部互转。当绑定或定义BLOB或CLOB数据时，应用必须注意定位符是使用OCI_DTYPE_LOB作为类型参数分配的。同样的，当绑定或定义BFILE数据时，应用必须注意定位符是使用OCI_DTYPE_FILE作为类型参数分配的。

OCI应用可以通过执行一个select列表中包含LOB列或LOB属性的SQL语句从数据库中检索LOB定位符。这种情景下，应用需要首先分配LOB定位符，然后使用这个LOB定位符定义一个输出变量。类似地，LOB定位符也可以用于绑定操作，在SQL语句占位符和一个LOB类型数据之间建立联系。

OCI 应用程序使用参数描述符来获取select列表的列信息或模式对象的信息。 该信息可以通过一个describe操作获取到。 参数描述符是唯一一个不通过OCIDescriptorAlloc()函数分配的描述符类型。只能通过调用OCIParamGet()函数指定参数位置，作为一个描述符句柄或语句句柄的属性，或通过一个复杂对象检索句柄来获取参数描述符。

ROWID描述符用于需要检索和使用Oracle ROWID类型数据的应用。为了使用ROWID类型，应用需为SQL的lelect列表中的rowid位置定义一个ROWID描述符，然后将ROWID数据获取到这个描述符中。这个描述符可以在之后绑定到一个INSERT语句或WHERE子句的输入变量上。 也可以通过在执行后的语句句柄上调用OCIAttrGet()将ORWID重定向到描述符中。

日期、时间以及间隔描述符在使用日期、时间或间隔数据类型(OCIDate,OCIDateTime,OICInterval)的应用程序中会用到。 这些描述符可以用于绑定和定义。可以作为参数传递给OCIDescriptorAlloc()和OCIDescriptorFree()，来完成内存的分配和释放。

当处理对象数据时，使用复杂对象检索(COR)可以提升应用性能。

Oracle Streams Advanced Queuing 提供消息队列作为 Oracle 数据库的一个集成部分。

OCIDescriptorAlloc()函数参数列表中有一个xtramem_sz参数。这个参数用于指定与一个描述符或定位符一起分配的用户内存的大小。 通常来说，应用使用这个参数分配一个与描述符或定位符具有相同生命周期的应用自定义数据结构。这个结构可以用于应用程序统计或存储上下文信息。 使用xtramem_sz参数意味着当每个描述符或定位符被分配或释放时，应用不需要显式地分配和释放对应自定义结构的内存。这部分用户数据结构的内存会随着描述符或定位符的分配而分配，随着描述符或定位符的释放而释放。 OCIHandleAlloc()也有一个类似的参数，允许分配与句柄有相同生命周期的用户内存。 OCIEnvCreate()和(OCIEnvInit()以弃用)也有一个类似的参数，允许分配与环境句柄有相同生命周期的用户内存。

本部分内容详细描述开发OCI应用程序的每一个步骤。其中有些步骤是可选的。例如，如果要执行的语句不是查询语句，则不需要对select列表中的内容进行描述和定义。 下面几个部分描述了OCI应用需要的步骤

这部分内容描述如何初始化OCI环境，创建到服务器的连接以及授权用户以执行数据库操作。 初始化OCI环境主要包含以下三个步骤：

每一个OCI函数的调用都需要在一个由OCIEnvCreate()创建的环境上下文中中进行。因此必须在执行任何其他OCI调用之前调用OCIEnvCreate()。唯一的例外是为OCI共享模式设置进程级属性。 OCIEnvCreate()的mode参数指定应用调用OCI库函数的时候是否能：

Oracle 数据库提供分配、释放句柄和描述符的OCI函数。在将句柄作为参数传递给其他OCI函数前，首先需要使用OCIHandleAlloc()分配该句柄，除非这个OCI函数分配句柄，例如OCIBindByPos()。 用户可以基于应用的功能需求，使用OCIHandleAlloc()分配句柄模块的表中列出的部分或所有类型的句柄。

应用程序必须调用 OCIEnvNlsCreate() 来初始化 OCI 环境句柄。 现有应用程序可能已使用 OCIEnvCreate()。 应用程序与Oracle数据库建立连接并开启一个用户会话需要遵循以下几个步骤：

注意： 建议开发应用时使用 OCIEnvCreate() 或 OCIEnvNlsCreate() 代替 OCIIInitialize() 和 OCIEnvInit() 。OCI仅为了兼容旧版支持OCIInitialize() 和 OCIEnvInit() 。

单个用户单个连接这种是最简单的登录方式，可以在应用对每个数据库连接仅维护一个用户会话的情况下使用 当应用调用OCILogon2()或OCILogon()时，OCI库对传递给它的服务上下文句柄进行初始化，为发请求的用户创建到指定Oracle数据库的连接。 下面例子是调用OCILogon2()，为用户名为hr密码为hr的用户创建到数据库oracledb的单个会话的使用方式：

OCILogon2()这个函数的参数包含服务上下文句柄(通过调用该函数完成了初始化)，用户名，密码，用于建立连接的数据库名。最后一个参数mode设置为OCI_DEFAULT时与调用OCILogon()函数的效果是一样的。在这个函数中服务器和用户会话句柄都被隐式地分配。建议新的应用都使用OCILogon2()。 如果应用使用单用户单连接的登录方式，服务上下文句柄，服务器句柄和用户会话句柄都是只读的。以你关于程序不能通过调用OCIAttrSet()改变服务上下文的特定属性来切换会话或事务。 使用OCILogon2()初始化会话和授权的应用必须使用OCILogoff()来结束它们。

注意： 为简化演示此功能，此示例没有使用生产系统通常使用的密码管理技术。 在生产环境中，遵循 Oracle 数据库密码管理指南，并禁用任何示例帐户。 有关密码管理指南和其他安全建议，请参阅 Oracle Database Security Guide。

代理身份验证通常是在具有中间层（例如防火墙）的环境中使用的过程，其中最终用户向中间层进行身份验证，然后中间层代表用户作为其代理向数据库进行身份验证。 中间层以代理用户身份登录数据库。 代理用户可以切换身份，并在登录数据库后切换到最终用户的身份。 它可以使用与特定最终用户相匹配的授权，代表最终用户执行操作。 OCI 和 ALTER USER 语句支持对数据库用户的代理，其 BNF 语法为：

ALTER USER 语句在应用程序中使用一次。 之后可以进行多次连接。 在 OCI 中，用户可以使用连接字符串或调用函数 OCIAttrSet()并传入参数OCI_ATTR_PROXY_CLIENT 。

非代理多会话或连接方式，通过显式地添加和调用启用会话函数来维护一个数据库连接上的多个用户会话和连接。 附加到 Oracle 数据库和开始会话的特定函数有：

再次调用OCISessionBegin()时使用不同的服务上下文句柄和会话上下文句柄会导致前一个用户登出，并引发错误。要想同时运行两个不可互相替代的会话，第二次调用OCISessionBegin()函数时必须指定一个相同的服务上下文句柄和一个新的会话上下文句柄。 下面例子描述了一个OCI环境的创建和初始化过程：

样例路径下的样例程序cdemo81.c中有对该过程包含错误处理的完整描述。

第 4 章概述了在 OCI 中处理 SQL 语句所涉及的具体步骤。

应用通过调用OCITransCommit()向数据库提交变更。这个函数使用一个服务上下文句柄作为参数之一。要提交变更的事务与服务上下文相关联。事务可以被应用显式地创建，也可以在执行数据库修改地时候隐式地创建。 回滚事务可以调用OCITransRollback()。 如果应用还未调用OCITransCommit()就以非正常登出的方式断开连接，例如失去网络连接，所有活动的事务都会被自动回滚。

一个OCI应用在结束前，需要执行以下步骤：

OCI函数有一组返回代码代表调用结果，这些返回代码可以表示调用成功还是失败，如OCI_SUCCESS或OCI_ERROR，也可以表示其他应用程序可能需要的状态信息，有OCI_NEED_DATA或OCI_STILL_EXECUTING。大多数OCI调用都会返回一种代码。 应用可以检查服务器句柄中的OCI_ATTR_SERVER_STATUS属性的值来确认到服务器的连接没有因OCI_ERROR而终结。如果属性的值为OCI_SERVER_NOT_CONNECTED，那么必须重新建立到服务器的连接和用户会话。 OCI中的返回错误代码见下表：

如果返回码显式发生了错误，应用程序可以调用OCIErrorGet()获取错误码和数据库的特定信息。OCIErrorGet()要传入的参数之一就是引发错误的错误句柄。

注意： 可以重复调用OCIErrorGet()获取多个诊断记录，直到没有更多可返回的记录(返回OCI_NO_DATA)。OCIErrorGet()至少返回一条诊断记录。

如下表所示，当获取的数据是正常、空值或截断时，对应的OCI返回码、错误号、指示符变量和列返回码。 表待补充。

有些函数不反悔OIC错误码，而是返回其他值。使用这些函数时，需要注意它们直接通过函数调用返回值，而不是通过OUT参数。关于每个函数及其返回值的更多详细信息参阅引用章节。

操作系统可能提供允许派生子进程重用母进程创建的状态的功能。在派生了一个子进程后，子进程不能使用母进程创建的同一个数据库连接。子进程使用与父进程相同的数据库连接的任何尝试都可能导致不希望的连接干扰并导致间歇性 ORA-03137 错误，因为 Oracle Net 期望只有一个用户进程使用与数据库的连接。 如果需要多个并发连接，当平台支持线程包时，建议考虑使用线程。 单线程或多线程应用程序都支持并发连接。 对于许多并发打开连接的情况，可以考量使用连接池来提高性能。

OCI函数使用大量的不同类型的参数，包含整数，句柄，字符串等。对于其中一些类型的参数需要特别关注。具体参照本章节的后续阐述。

地址类型参数用于将变量的地址传递给Oracle数据库。当使用C语句开发的时候，需要特别注意，因为C语言中通常是传递标量参数的值。

二进制整数和短二进制整数类型参数的大小取决于系统。用户需查阅特定操作系统的Oracle数据库文档来确定所使用操作系统中这类整型的大小。

字符串类型是地址类型参数中的特殊一类。每个允许传入一个字符串类型做参数的OCI函数都会同时有一个字符串长度参数。长度参数应设置为爱风尘的长度。

往数据库列中插入一个空值可以有以下几种方式：

对于一个DML语句，一个PL/SQL语句或一个查询语句而言，每个OCI绑定和定义调用都有一个与指示符变量或指示符变量数组相关联的参数。 C语言没有空值的概念，因此，用户需要将指示变量与输入变量关联以指定对应的占位符是否为 NULL。 当数据传递到 Oracle 数据库时，这些指示变量的值决定是否将 一个数据库字段设置为NULL。 对于输出变量，指示符变量决定从Oracle返回的值是NULL还是被截断的值。如果OCIStmtFetch2()调用获取NULL值或者OCIStmtExecute()调用发生截断，OCI调用将会返回OCI_SUCCESS_WITH_INFO。 指示符变量的数据类型是sb2。对于指示符变量数组来说，每个数组元素应该是sb2类型。

对于输入的主机变量来说，OCI应用允许指示符变量设置为下面的值：

对于输出变量的指示符变量，Oracle数据库可以将指示符变量设置为以下值：

在8.0之后的版本中，大多数数据类型的指示符变量都如之前所描述的。唯一的例外是SQLT_NTY(一个命名的数据类型)。对于数据类型SQLT_NTY，指示符变量必须是一个指向指示符结构的指针。SQLT_REF数据类型与其他变量类型一样，都使用一个标准的标量指示符。 当使用对象类型转换器 (OTT) 将数据库类型转换为 C 结构表示时，将为每个对象类型生成一个空指示符结构。 此结构包括一个原子空指示符，以及每个对象属性的指示符。

待补充

待补充

待补充

OCI中有一些通过轮询模式完成的函数调用。这类轮询模式的调用函数有：

待补充

待补充

待补充

待补充

待补充