Oracle-OCI(Oracle-Call-Interface)官方文档翻译

OCI学习资料--Oracle8及以后版本的OCI1.简介Oracle调用接口(OracleCallInterface)是一个让我们通过函数调用来访问Oracle数据库和控制SQL语句执行各个阶段的应用程序编程接口(API)。OCI支持C和C++的数据类型、调用惯例、语法和语义。1.1创建一个OCI应用程序我们编译和连接一个OCI程序的方法与编译和连接一个非数据库应用程序的方法相同。不需要独立的预处理或者预编译步骤。1.2OCI的组成部分OCI具有如下功能：·能够安全地支持大量用户的灵活的、多线程API集合。·为管理数据库访问、处理SQL语句和管理Oracle数据库对象的SQL访问函数。·管理Oracle类型的数据属性的数据类型映射和操作函数。·不经SQL语句直接向数据库加载数据的数据加载函数。1.3封装的接口所有的OCI函数使用的数据结构都以被称为句柄的不透明的接口之形式封装。句柄是指向OCI库分配的保存着上下文信息、连接信息、错误信息或者关于SQL及PL/SQL的绑定信息的不透明指针。客户端分配一定类型的句柄，通过已经定义好的接口来填充一个或者多个句柄，并通过这些句柄向服务器发送请求。应用程序可以通过访问函数来访问句柄中包含的相关信息。2.OCI基本编程这部分介绍OCI编程中涉及到的基本概念。2.1OCI编程概要一个OCI应用程序的基本目标就是代表多个用户进行数据库操作。OCI使用以下基本编程顺序：1.初始化OCI编程环境和线程。2.分配必要的句柄，并且设置服务器连接和用户会话。3.通过在服务器上执行SQL语句来交换数据，并且执行必要的应用程序数据处理。4.执行准备好的语句或者准备即将要执行的语句。5.终止用户会话并且断开服务器连接。6.释放句柄。图2-1显示了一个OCI应用程序的编程步骤。图2-1这幅图及其所列出的步骤提供了一个OCI编程步骤的简单概括。根据程序的功能，变化是完全可能发生的。包含管理多个会话、事务和使用对象的更复杂的OCI应用程序需要另外的步骤。所有的OCI函数调用都在一个环境中执行。在一个OCI进程中可以有多个环境。如果一个环境需要任何进程级别的初始化，则其自动进行。注意：在一个OCI应用程序中可以有多个活动连接和语句。2.2OCI数据结构句柄(Handles)和描述符(descriptors)是OCI应用程序中定义的不透明的数据结构。它们可以被直接分配、通过特殊的分配函数或者可以被OCI函数隐式地分配。7.X升级注意：以前写过7.XOCI应用程序的程序员必须熟悉这些被大多数OCI函数使用的数据结构。句柄和描述符保存有关数据、连接、或者应用程序行为的信息。2.3句柄几乎每一个OCI函数的参数列表中都包含有一个或者多个句柄。一个句柄是一个指向一个OCI库分配的存储区域的不透明的指针。我们使用句柄来保存上下文信息或者连接信息，(例如，一个环境或者服务句柄)，或者它可以保存关于OCI函数或者数据的信息(例如，一个错误句柄或者描述句柄)。句柄可以使编程更简单，因为OCI库会维持这些数据而不是应用程序。大多数OCI应用程序需要使用句柄中的信息。获取属性值和设置属性值的OCI函数，OCIAttrGet()和OCIAttrSet()，获取和设置这些信息。表2-1列出了OCI中定义的句柄。并列出了与每一种句柄类型相对应的C数据类型和OCI函数中使用的用来识别OCI调用中的句柄类型的句柄类型常量。表2-1OCI句柄类型分配和释放句柄我们的应用程序要为一个特定的环境句柄分配所有的句柄(除了绑定句柄bindhandle、定义句柄definehandle和线程句柄threadhandles)。我们把环境句柄作为一个参数传递至句柄分配函数。然后，被分配的句柄就特定于那个特定的环境。绑定句柄和定义句柄是为一个语句句柄分配的，并且包含了关于那个句柄所代表的语句的信息。注意：绑定句柄和定义句柄是由OCI库隐式分配的，不需要用户分配。图2-2显示了不同类型的句柄的层次图2-2句柄的层次环境句柄是由OCIEnvCreate()或者OCIEnvNlsCreate()函数分配和初始化的，所有的OCI程序都需要执行它们中的任一个。所有的用户分配的句柄都通过OCI句柄分配函数来初始化，即OCIHandleAlloc()函数。句柄类型包括：线程句柄、描述句柄、语句句柄、服务上下文句柄、错误句柄和服务器句柄等。线程句柄通过OCIThreadHndInit()函数分配。一个应用程序必须释放所有的不再使用的句柄。OCIHandleFree()函数释放所有的句柄。注意：当一个父句柄被释放后，所有与之相连的子句柄也被释放并且再也不能被使用。例如，当一个语句句柄释放后，任何与之相连的绑定和定义句柄也都被释放。句柄减少了对全局变量的需要。句柄也使错误报告更容易。一个错误句柄用来返回错误和诊断信息。2.3.1环境句柄环境句柄提供了一个所有的OCI函数被调用的上下文。每一个环境句柄包含一个支持快速访问的内存缓存。所有的环境句柄下的内存分配都是通过这个缓存完成的。如果多个线程想要在同一个环境句柄下分配内存，则它们对缓存的访问是序列化的。当多个线程共享一个单独的环境句柄时，它们会阻塞对缓存的访问。环境句柄作为OCIHandleAlloc()函数的parent参数来分配其他句柄类型。绑定句柄和定义句柄是隐式分配的。2.3.2错误句柄错误句柄作为一个参数传递至大多数OCI函数。错误句柄维持着关于一个OCI操作中所发生的错误的信息。如果一个函数调用中发生了一个错误，错误句柄可以传给OCIErrorGet()函数来获取关于那个错误的额外信息。由于大多数OCI函数都需要一个错误句柄作为一个参数，分配错误句柄是一个OCI应用程序中的前几个步骤之一。2.3.3服务上下文句柄和相关的句柄一个服务上下文句柄定义了决定OCI调用的上下文的属性。服务上下午句柄包含3个句柄作为它的属性，分别代表一个服务器连接、一个用户会话和一个事务。图2-3列出了这些属性图2-3·一个服务器句柄ServerHandle识别对一个数据库的连接。·一个用户会话句柄UserSessionHandle定义了一个用户的角色和权限以及函数执行的操作上下文。·一个事务句柄定义了SQL操作所属的事务。在需要更复杂的会话管理的应用程序中，服务上下午句柄必须被显式地分配，并且服务器句柄和用户会话句柄必须通过OCIAttrSet()函数被显式地设置到服务上下午句柄中。OCIServerAttach()函数和OCISessionBegin()函数分别初始化服务器和用户会话句柄。当应用程序对数据库做修改时，OCI自动隐式分配的事务句柄正确地工作。2.3.4语句句柄、绑定句柄和定义句柄一个语句句柄是识别SQL或者PL/SQL语句以及与之相连的属性的上下文，如图2-4所示图2-4关于输入绑定变量和输出绑定变量的信息储存于绑定句柄中bindhandle。OCI库为每一个与OCIBindByName()函数或者OCIBindByPos()函数相连的占位符分配一个绑定句柄。用户一定不可以分配绑定句柄。它们是由绑定函数隐式分配的。查询返回的数据根据定义句柄(definehandle)的描述来转换和获取。OCI库为每一个OCIDefineByPos()函数中所定义的输出变量分配一个定义句柄。用户一定不可以分配定义句柄。它们是由定义函数隐式分配的。绑定句柄和定义句柄是由OCI库显式分配的，并且如果绑定或者定义操作是重复的话，绑定句柄和定义句柄是被重复使用的。当语句句柄被释放或者当一个新的语句被准备到语句句柄上后，绑定句柄或者定义句柄就被释放。显式分配绑定或者定义句柄可能导致内存泄露。显式释放绑定句柄或者定义句柄可能导致程序异常终止。2.3.5描述句柄描述句柄describehandle由OCI描述函数所使用，OCIDescribeAny()。这个函数获取关于数据库中的数据库对象的信息(例如,函数或者过程)。这个函数有一个参数是描述句柄，以及关于被描述的对象的附加信息。当函数执行完成后，描述句柄就存有关于那个对象的信息。然后OCI应用程序可以通过参数描述符的属性获取描述信息。2.3.6句柄属性所有的OCI句柄都有表示存储在那个句柄中的数据的属性。我们可以通过属性获取函数OCIAttrGet()来获取句柄属性值，并且我们可以通过OCIAttrSet()函数来设置句柄的属性值。例如，下面的代码显示了通过写入会话句柄的OCI_ATTR_USERNAME属性来设置会话句柄中的用户名。textusername[]=“hr”;err=OCIAttrSet((dvoid*)mysessp,OCI_HTYPE_SESSION,(dvoid*)username,(ub4)strlen((char*)username),OCI_ATTR_USERNAME,(OCIError*)myerrhp);一些OCI函数要求在这些函数被调用前，一些特定的句柄属性值被设置。例如，调用OCISessionBegin()函数来设置用户的登录会话，在这个函数被调用之前，必须设置用户会话句柄的用户名和密码属性。其他的OCI函数执行完成后，会在句柄属性中提供有用的返回数据。例如，当OCIStmtExecute()函数被调用来执行SQL查询时，关于所选字段的描述信息被返回到语句句柄中。ub4parmcnt;/*获取选择列表中的字段数量*/Err=OCIAttrGet((dvoid*)stmhp,(ub4)OCI_HTYPE_STMT,(dvoid*)&parmcnt,(ub4)0,(ub4)OCI_ATTR_PARM_COUNT,errhp);2.3.7OCI描述符OCI描述符descriptor和定位符locator是维护特殊数据信息的不透明数据结构。表2-2列出了它们以及对应的C数据结构和还有在OCIDescriptorAlloc()函数中所用到的OCI类型常量。OCIDescriptorFree()函数释放描述符和定位符。表2-2下面描述了各种描述符类型的主要目的。·OCISnapshot—用于语句执行·OCILobLocator—用于LOB(OCI_DTYPE_LOB)或者BFILE(OCI_DTYPE_FILE)函数·OCIParam—用于描述函数·OCIRowid—用于绑定或者定义ROWID值2.3.7.1LOB和BFILE定位符一个大对象(LOB)是保存二进制大数据或者字符大对象(CLOB)数据的Oracle数据类型。在数据库中，一个不透明的叫做LOB定位符的数据结构保存在一个数据库行的LOB字段中。定位符作为实际LOB值的指针，实际的LOB值保存在其他的地方。OCILOB定位符用于对LOB(BLOB或者CLOB)类型或者FILE(BFILE)类型进行OCI操作。OCILobXXX函数使用LOB定位符作为参数而不是LOB数值。OCILOB函数不使用实际的LOB数据作为参数。它们使用LOB定位符作为参数并且通过引用它们来操作LOB数据。通过向OCIDescriptorAlloc()函数传递OCI_DTYPE_LOB作为类型参数来为BLOBs或者CLOBs分配LOB定位符，传递OCI_DTYPE_FILE作为类型参数为BFILEs分配LOB定位符。注意：这两种LOB定位符类型是不能互换的。当绑定或者定义一个BLOB或者CLOB时，应用程序必须注意定位符是否是通过OCI_DTYPE_LOB分配的。同样，当绑定或者定义一个BFILE时，应用程序必须确保使用OCI_DTYPE_FILE分配定位符。一个OCI应用程序可以使用一个包含有LOB字段或者属性的SQL语句从Oracle数据库获取LOB定位符。这种情况下，应用程序需要首先分配LBO定位符然后用它来定义一个输出变量。与此类似，一个LOB定位符可以被用来作为绑定操作的一部分以创建一个LOB和一个SQL语句中的占位符的联结。2.3.7.2参数描述符OCI应用程序使用参数描述符获取关于所选字段或者数据库对象的信息。通过描述操作获