Oracle Database Development (7).  The thinking of the OCI example .

Vert Melon

Jun 26,2007

 The central content in this article is about the common operations with Oracle .  Just  
follow the instructions and enrich the relevant knowledge by the OCI official document .
I'd like to copy many sentences from OCI official document . It would save me many 
trouble and these sentences are more exactly .

1. Connection

 Connection is surely a first step done with the database . OCI provides two mode of 
connection , which is Single User, Single Connection and Multiple Sessions or Connections.
 The example also gave the both implement .

 a. Single User, Single Connection 
 -----------------------------------------------------------------------------
 
 An application maintains only a single user session for each database connection 
at any time .
 
 The corresponding functions in the example listed as follows :
 OCIDB::Single_Conn()
 OCIDB::Single_Disc()
 
 The calling order of routines :
 
 OCIEnvCreate
 OCIHandleAlloc  <ERROR>
 OCILogon
 
 OCILogoff
 OCIHandleFree   <ERROR>
 OCIHandleFree   <ENV>
 
 An application of OCI must have one environment handle , which is created by OCIEnvCreate() 
here . The environment handle defines a context in which all OCI functions are invoked . 
It is the base of almost all of the other handles which would be seen in future.
 OCIEnvCreate() creates and initializes an environment for OCI functions to work under .
 This call should be invoked before any other OCI call and should be used instead of
the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be 
supported for backward compatibility. But if you are writing a DLL or a shared library 
using OCI library then this call should definitely be used instead of OCIInitialize() and 
OCIEnvInit() call . OCIInitialize() and OCIEnvInit() call is used in OCIDB::Multiple_Conn() , 
we'll cover it soon.
  
 Almost all OCI calls include in their parameter list one or more handles. A handle is an 
opaque pointer to a storage area allocated by the OCI library. You use a handle to store 
context or connection information, (for example, an environment or service context handle), 
or it may store information about OCI functions or data (for example, an error or describe 
handle). Handles can make programming easier, because the library, rather than the application, 
maintains this data.

 Either OCIEnvCreate() or ( OCIInitialize() and OCIEnvInit() ) allocates a environment 
handle . I defined a private member variable named m_pOCIEnv to store it . You can find
 the both routines return a address as environment handle .

 There is also a very important handle , which appears in mostly OCI calls . That is the 
error handle .The error handle maintains information about errors that occur during an OCI 
operation. If an error occurs in a call, the error handle can be passed to OCIErrorGet() to 
obtain additional information about the error that occurred.
 Go and look at OCIException::CheckError() which shows a integral error management .

 After the preparation of Environment and Error , we will come to the actual code about 
the connection . OCILogon() and OCILogoff() is quite easy to us . Notice that  a service 
context handle will be created during the time processing OCILogon(). 
 A service context handle defines attributes that determine the operational context for 
OCI calls to a server. The service context contains three handles as its attributes, that 
represent a server connection, a user session, and a transaction.  OCILogon() call also 
implicitly allocates server and user session handles associated with the session.

 Is is a very good custom that release the resource allocated at first in an order when 
the program comes the end . OCIDB::Single_Disc() does it explicitly .

 b. Multiple Sessions or Connections
 -----------------------------------------------------------------------------
 
 If an application needs to maintain multiple user sessions on a database connection, 
the application requires a different set of calls to set up the sessions and connections.

 The corresponding functions in the example listed as follows :
 OCIDB::Multiple_Conn()
 OCIDB::Multiple_Disc()
 
 The calling order of routines :
 
 OCIInitialize
 OCIEnvInit
 OCIHandleAlloc  <Error>
 OCIHandleAlloc  <Server Context >
 
 OCIHandleAlloc  <Server>
 OCIAttrSet  <Set Server Into ServerContext>
 OCIServerAttach <AttachServer>
 
 OCIHandleAlloc  <Session>
 OCIAttrSet  <Set Session Into ServerContext>
 OCISessionBegin
 
 ...
 
 Compare with OCILogon() it becomes more complex . Each handle is allocated by 
hand here .
 There is someting new . All OCI handles have attributes associated with them. These 
attributes represent data stored in that handle. You can read handle attributes using the 
attribute get call, OCIAttrGet(), and you can change them with the attribute set call,  
OCIAttrSet(). OCIServerAttach() creates an access path to the data server for OCI 
operations. OCISessionBegin() establishes a session for a user against a particular server. 
 This call is required for the user to be able to execute any operation on the server. 
 Notice that the calling order of OCIAttrSet() or OCIServerAttach() is random . As the
same , either call OCIAttrSet() before OCISessionBegin() or call OCISessionBegin()  
before OCIAttrSet() is OK .

 You can change the content of the file Main.cpp to implement the different operation . 
Some code for test is listed below :

 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Single_Conn();
     db.Single_Disc(); 
     
 } 
 
 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Multiple_Conn();
     db.Multiple_Disc(); 
     
 }

2. Execute non-query SQL

 Non-query SQL means that SQL doesn't return any data , such as create , insert , delete
and so on . These SQL statements also could be comprehanded as DDL . OCI also support 
the bind for extern values and we will discuss it in next section.  Please search the relevant 
code in the example.  The function OCIDB::ExecuteSql() covers it .

 At first you should allocate a statement handle in the envionment handle. A statement 
handle is the context that identifies a SQL or PL/SQL statement and its associated attributes.
Every SQL statement must be prepared for execution by OCIStmtPrepare() then. This is a 
completely local call, requiring no round trip to the server. No association is made at this 
point between the statement and a particular server.

 After finished the steps above , call OCIStmtExecute() to execute the statement. For DDL 
statements, no further steps are necessary.

 You may use these code statements in Main.cpp as the following :
 
 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Multiple_Conn();
     db.ExecuteSql("update liwei_test  set id =123 where note='test' ");
     db.Multiple_Disc(); 
     
 }

 
3. Bind variable
 
 Most DML statements, and some queries (such as those with a WHERE clause), require a 
program to pass data to Oracle as part of a SQL or PL/SQL statement. Such data can be constant 
or literal data, known when your program is compiled.

 insert into liwei_test (id,name,note)values(1,'aABD','cadsf')

 This statement is a simple one to insert some data known. When you prepare a SQL statement 
or PL/SQL block that contains input data to be supplied at runtime, placeholders in the SQL statement 
or PL/SQL block mark where data must be supplied. For example, the following SQL statement 
contains three placeholders, indicated by the leading colons (for example, :id), that show where 
input data must be supplied by the program.

 insert into liwei_test (id,name,note)values(:id,:name,:note)
 
 In this example I also made two different way using the bind .  Look at this content of Main.cpp :

 A. One-off bind with a predefine structure

 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.BindAddVar(":id", 19809);
   db.BindAddVar(":name", "liwei");
   db.BindAddVar(":note", "test");
   db.BindSql("insert into liwei_test (id,name,note)values(:id,:name,:note) ");
   db.BindAddVar(":id", 169);
   db.BindAddVar(":name", "sstem ch");
   db.BindSql("insert into liwei_test (id,name)values(:id,:name) ");
   db.Multiple_Disc(); 
   
 } 
 
 OCIDB::BindAddVar() add the user parameters into the share variable which name 
is m_BindVars . It has several overrided patterns .
 OCIDB::BindSql() execute the SQL statement binding the structural variable . All of 
the OCI operation needed is called in an order . 
 
 Notice :  OCIDB::BindAddVar() allocates memory automaticly as the bind variable need .
 
 
 B.  Bind the variable step by step consistent with the defined order of OCI

 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.UserPrepare("insert into liwei_test (id,name,note)values(:id,:name,:note)");
   db.UserBind(":id",10701);
   db.UserBind(":name", "liweitest");
   db.UserBind(":note", "asdfasdf");
   db.UserExecute();
   db.UserCommit();
   db.UserFree();
   db.Multiple_Disc(); 
   
 }  
 
 The process had been divided into several steps here . In this case you can extend some 
further functions more easily . 

 Notice :  The class function starts with "User" is a series which performs a common template .

 
 Both the two methods above follow this calling order :
 
 OCIHandleAlloc  <stmt>
 OCIStmtPrepare
 OCIBindByName/OCIBindByPos
 OCIStmtExecute
 OCITransCommit/OCITransRollback
 OCIHandleFree  <stmt>
 
 
4. Get the Recordset from a SQL Select statement

 In this section i'd like to introduce a simple query example about the select statement which
 select-list cols is known before execution. 
  Query statements return data from the database to your application.  When processing a query, 
 you must define an output variable or an array of output variables for each item in the select-list 
 from which you want to retrieve data.

 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.UserSelect("select id,name,note,value from liwei_test where note='test'");
   while(db.UserFetch()==0) {
    printf("id:%f\n", db.UserGetFloat("id"));
    printf("name:%s\n", db.UserGetString("name"));
    printf("note:%s\n", db.UserGetString("note"));
    printf("value:%f\n\n", db.UserGetFloat("value"));
   }
   db.UserSelectFree();
   
 }  
 
 As you see ,  a simple one is gave now , which still seems a bit complex . Firstly i defined 
a structure "TSelectVar"  to store select-list . "TSelectVar" had a union to store values in 
different type . Then i encapsuled the select operation into the four parts .

 UserSelect
 UserFetch
 UserGet
 UserSelectFree 
 
 So let's have a look at the first part --  OCIDB::UserSelect() .

 OCIHandleAlloc() , OCIStmtPrepare(), OCIStmtExecute() and then the OCIAttrGet() !
 I want to know the column count of the select-list , so used OCIAttrGet() there . For each 
 column , i called OCIParamGet() to get a OCI parameter and then used OCIAttrGet() to 
 fetch lots of useful imformation such as name, size, presision and so on .
 
 After the get of attribute , you should define the content of the select-list using OCIDefineByPos()
 or OCIDefineByName() then.
 
 The purpose of these Get() and Define() calls is to describe the select-list for the following 
 action which is get .  OCIDB::UserFetch() is easily comprehanded , for only one call OCIStmtFetch
 in it .
 
 Pay attention to the member function like OCIDB::UserGet , these functions is interface 
 to exterior user . It is overrided also .
 
   int UserGetInt(int index);
   int UserGetInt(char * name);
   char * UserGetString(int index);
   char * UserGetString(char * name);  
   float UserGetFloat(int index);
   float UserGetFloat(char * name); 
   
 Peruse the code patiently and you will gain much knowledge .
 
5.The Last

 This example is just for a demonstration or a accidence . You mush not stop here only . 
Take this way for more info by practice and online help. Obviousely there are many points 
which are not very standard in the article , for a exam i didn't use CONST while passing a 
value . This is a important aspect to improve .
   For you may not acclimatize youself  to the variety of the OCI type , take it easy , try to
get together with the OCI Function Reference and force a type conversion .

-------------------------------------------------------------------------------------------------------

Oracle数据库开发(七).OCI示例开发说明

草木瓜

2007-6-26

 这篇文章的主要内容是介绍的常见的OCI数据操作。可以顺着文章思路结合OCI
相关Oracle文档去理解。这里从原文档中复制了不少原句，这个省了很多麻烦而且
这些表达更为准确。

一、数据库连接

 数据库连接是操作数据库的第一步。OCI提供了两种模式的连接，即单用户
单连接和多用户多连接。我这里的OCI示例也分别提供了两种实现方式。

 a.单用户，单连接
 -----------------------------------------------------------------------------
 
 应用程序对于某一数据库连接仅支持单用户进程。
 
 例子中对应的函数过程：
 OCIDB::Single_Conn()
 OCIDB::Single_Disc()
 
 OCI内部过程的调用顺序如下：
 
 OCIEnvCreate
 OCIHandleAlloc  <ERROR>
 OCILogon
 
 OCILogoff
 OCIHandleFree   <ERROR>
 OCIHandleFree   <ENV>
 
 OCI应用程序必须有一个环境句柄，在这里由 OCIEnvCreate()创建。环境句柄相当
于定义一个容器，包含了以后的所有OCI句柄，这是OCI调用的基础。
 OCIEnvCreate()创建并初始化了一个OCI函数的工作环境，必须先于其他OCI函数
之前调用。一般来说，从兼容性方面考虑，最好使用OCIInitialize() 和 OCIEnvInit()替代
OCIEnvCreate()。不过如果你在写dll或者共享库之类的东西，最好还是用OCIEnvCreate()。
OCIDB::Multiple_Conn()中就使用了OCIInitialize()和OCIEnvInit() ，我们一会会提到。
 
 绝大多数的OCI调用都使用了一个或多个句柄。句柄指向由OCI库自动分配的内存
空间。可以存储连接环境信息(如，数据库连接环境或服务环境句柄) ，OCI函数执行
过程中相关信息(如，错误句柄或者描述句柄)。OCI句柄让开发工作变得简单起来，
这些相关信息是由OCI库所管理，而不是用户的应用程序。

 不管是OCIEnvCreate()还是(OCIInitialize()和OCIEnvInit())都分配了一个数据库环境句
柄。我这里定义了私有成员变量m_pOCIEnv用来存储环境句柄。

 OCI中还有一个很重要的句柄，经常出现在OCI调用过程中。这就是错误句柄。错误
句柄管理在OCI数据操作中出现的各类错误，如果在调用中出错，可以把错误句柄
传递给OCIErrorGet()来获取更多的错误信息。
 OCIException::CheckError() 是一个完整的错误处理示例。
 
 准备好环境句柄和错误句柄后，该到数据库连接的实际代码了。这里的OCILogon() 
和 OCILogoff() 理解起来并不难。要注意OCILogon()执行过程中返回了一个服务环境
句柄。
 服务环境句柄定义一些重要属性，直接决定了连接数据库的方式方法。服务环境
句柄包含三个属性，其实就是另外独立的三个句柄，即服务连接，用户会话和事务。
 OCILogon()执行过程中其实也声明了服务连接和用户会话的相关句柄，只不过是隐
式声明。

 在程序结束时手工释放资源是很好的习惯，可参见OCIDB::Single_Disc()。
 
 b.多用户，多连接
 -----------------------------------------------------------------------------

 如果应用程序对单一数据库连接需要维护多个用户会话，就需要使用另一种方式了。
 
 例子中对应的函数过程：
 OCIDB::Multiple_Conn()
 OCIDB::Multiple_Disc()
 
 OCI内部过程的调用顺序如下：
 
 OCIInitialize
 OCIEnvInit
 OCIHandleAlloc  <Error>
 OCIHandleAlloc  <Server Context >
 
 OCIHandleAlloc  <Server>
 OCIAttrSet  <Set Server Into ServerContext>
 OCIServerAttach <AttachServer>
 
 OCIHandleAlloc  <Session>
 OCIAttrSet  <Set Session Into ServerContext>
 OCISessionBegin
 
 ...
 
 与OCILogon()相比，变的有些复杂，每个句柄在这里都是手工去创建。需要提出
的是，所有的OCI句柄都有其相关属性，这些属性存储了一些有用的数据。可以使
用OCIAttrGet()获取对应信息，也可以通过OCIAttrSet()进行修改。OCIServerAttach() 
创建了一个OCI操作的数据服务访问路径，OCISessionBegin() 确立用户会话连接。
这里完成后，才可以进行实际的数据操作。
 注意这里的OCIAttrSet()和OCIServerAttach()的调用顺序不是固定的，类似的 OCISessionBegin() 
和 OCIAttrSet() 先后顺序也是可以互换的。

 你可以自行更改Main.cpp内容以完成不同的数据操作。
 
 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Single_Conn();
     db.Single_Disc(); 
     
 } 
 
 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Multiple_Conn();
     db.Multiple_Disc(); 
     
 }

二、执行无返回值的SQL语句

 这类语句一般包括create , insert和delete等等，无返回值语句一般也可以理解为DDL
语句。OCI也支持对SQL语句进行变量绑定，下节会专门讨论。
 例子中相关的函数是OCIDB::ExecuteSql() 。
 
 首先你需要在环境句柄中声明一个语句句柄。语句句柄包含了SQL或者PL/SQL
语句及其相关属性，每个SQL语句在执行前必须要使用OCIStmtPrepare()进行预处理。
这个是本地化调用，不会向服务器端发送请求。

 完成上面步骤后，就可以调用OCIStmtExecute() 执行SQL语句了。
 
 代码语句如下：
 
 #include "OCIDB.h"
 int main() {
 
    OCIDB db;
     db.Multiple_Conn();
     db.ExecuteSql("update liwei_test  set id =123 where note='test' ");
     db.Multiple_Disc(); 
     
 }
 
三、变量绑定

 大多数DML语句或者一些查询(带where条件的)需要向SQL传递一些数据，下面的例子
是在程序编译时就已经知道要传递的数值。

 insert into liwei_test (id,name,note)values(1,'aABD','cadsf')
 
 这是个简单的例子，当预处理一个SQL语句或者PL/SQL块，其中有些数值是需要在运
行中才能确定的。这时就需要在运行动态去绑定变量了，我们在SQL语句或者PL/SQL块
中使用:id之类的符号，表示可以做为变量绑定。如：

 insert into liwei_test (id,name,note)values(:id,:name,:note)
 
 这个例子中，我使用了两种途径来绑定变量。
 
 A.通过预定义的结构体一次性绑定
 
 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.BindAddVar(":id", 19809);
   db.BindAddVar(":name", "liwei");
   db.BindAddVar(":note", "test");
   db.BindSql("insert into liwei_test (id,name,note)values(:id,:name,:note) ");
   db.BindAddVar(":id", 169);
   db.BindAddVar(":name", "sstem ch");
   db.BindSql("insert into liwei_test (id,name)values(:id,:name) ");
   db.Multiple_Disc(); 
   
 }
 
 OCIDB::BindAddVar() 将相关的用户变量参数添加到m_BindVars变量中，这个函数
有不同的重载形式。
 OCIDB::BindSql() 绑定结构体定义的变量，并执行SQL语句。
 
 注意：OCIDB::BindAddVar() 根据绑定的变量值自动分配内存
 
 B. 根据OCI内部顺序一步一步绑定
 
 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.UserPrepare("insert into liwei_test (id,name,note)values(:id,:name,:note)");
   db.UserBind(":id",10701);
   db.UserBind(":name", "liweitest");
   db.UserBind(":note", "asdfasdf");
   db.UserExecute();
   db.UserCommit();
   db.UserFree();
   db.Multiple_Disc(); 
   
 }  
 
 这里把整个过程划分成多步，可以方便以后扩展功能。
 
 注意：User打头的这些系列函数，其实是比较常用的一套模板。
 
 这两种方式调用OCI内部函数的顺序都是一样的：
 
 OCIHandleAlloc  <stmt>
 OCIStmtPrepare
 OCIBindByName/OCIBindByPos
 OCIStmtExecute
 OCITransCommit/OCITransRollback
 OCIHandleFree  <stmt>s
 
四、从Select语句获取记录集

 这节主要介绍一个简单的查询例子，例子中的查询列在执行前已经知道。
 查询语句返回数据库中所需数据，执行查询时必须要定义外部的输出变量或者变
量数组来存储你所需要检索的数据。

 #include "OCIDB.h"
 int main() {
 
   OCIDB db;
   db.Multiple_Conn();
   db.UserSelect("select id,name,note,value from liwei_test where note='test'");
   while(db.UserFetch()==0) {
    printf("id:%f\n", db.UserGetFloat("id"));
    printf("name:%s\n", db.UserGetString("name"));
    printf("note:%s\n", db.UserGetString("note"));
    printf("value:%f\n\n", db.UserGetFloat("value"));
   }
   db.UserSelectFree();
   
 }  
 
 上面就是一个小例子。首先我先定义了一个结构体TSelectVar(与绑定变量的结构体
类似)准备存储返回的结果集。TSelectVar 中使用了Union存储不同类型的数值。然后
我把整个OCI Select过程封装成如下四部分：
 
 UserSelect
 UserFetch
 UserGet
 UserSelectFree 
 
 我们先看第一部分 OCIDB::UserSelect() 。
 OCIHandleAlloc() , OCIStmtPrepare(), OCIStmtExecute() 然后是OCIAttrGet() 。
 OCIAttrGet()主要是为了获取返回结果集的列数。对于每一列，使用了OCIParamGet()
 先获取整列的OCIParm，然后再使用OCIAttrGet()依次获取象列名，列大小，精度等
 有用的信息。
 
 获取这些属性后，就需要调用OCIDefineByPos()或OCIDefineByName为结果集定义
 内容了。
 
 其实这些Get()和Define()就是为了描述Select执行后返回的结果集，方便我们获取其中
 数据。OCIDB::UserFetch() 里面只有个OCIStmtFetch()，比较好理解，说白了就是控制
 游标。
 
 注意象OCIDB::UserGet的这些个成员函数，是对外的数据接口，以下是不同的重载形
 式：
 
   int UserGetInt(int index);
   int UserGetInt(char * name);
   char * UserGetString(int index);
   char * UserGetString(char * name);  
   float UserGetFloat(int index);
   float UserGetFloat(char * name); 
   
 这里没有什么好说的，读读代码就会清楚。
 
五、写在最后

 这个例仅做演示。不过不必仅停留于此，如要提高，结合在线文档多练即可。
这个例子的代码在某些方面显然不够规范，如未在传值中使用const，这也是以后
要提高的方面。
 另外，刚接触OCI时，可能会对内部的一堆类型不太适应，这里多看看函数的参考，
尽量做一些强制性的转换。 

Oracle Database Development (6). A first exploration of OCI

Vert Melon

Jun 25,2007

1.Preface

 Last time , i provided a full example of OCI , which contains the actual code of connection 
and SQL . Certainly it could not cover all of the knowledge , but i think it is a good beginning 
for the fresher .

 As the same as Pro*C you might confirm that you have installed it correctly .  Look at this 
paths as follows :
 
 Windows   :   $ORACLE_HOME\oci
 Linux/Unix  :   $ORACLE_HOME/rdbms/demo
 
 There are many examples offered by ORACLE . Though it seems like a clutter , you also 
can get some useful imformation .

 The main platform we use here is Linux .  And the Windows ?  How can i config it in Windows ? 
It would be a comfy thing if you have read the chapters recorded in  <Oracle Database Development (1). Config OCI In Windows> .
It is easily comprehend by analogy .

2.Something you should know

 What is the Oracle Call Interface?

 The Oracle Call Interface (OCI) is a set of low-level APIs (Application Programming Interface Calls) 
used to interact with Oracle databases. It allows one to use operations like logon, execute, 
parse, fetch, etc. OCI programs are normally written in C or C++, although they can be written
in almost any programing language. Unlike with the Oracle Precompilers (like Pro*C and Pro*COBOL), 
OCI programs are not precompiled.

 Also I have found a official explaination about the choice between Pro*C and OCI .
 
 Should one use OCI or the Oracle Precompilers?
 
 OCI is superior to Pro*C in the following ways: 
  Performance is much better with OCI 
  Reduced code size 
  Direct access to built-in functions (No intermediate files or substitutions). 
  Piecewise Operation on LONG fields (All LONG field problems are solved) 
  In Pro*C one cannot dynamically allocate memory to be used as bind variables 
  You cannot control the Pro*C precompiler to provide better and more compilable C-code. 
  ...
   
 Common problems with OCI: 
  OCI code is difficult to write and to maintain 
  Very few people can write, let alone maintain OCI code 
  ...
  
 An OCI application program must do the following: 
  Connect to one or more databases: call the OCILogon (olog, olon or orlon) routines 
  Open the cursors needed by the program: use oexec, oexn, ofen or oftech calls. 
  Process the SQL statements that are needed to perform the application's tasks. 
  Close the cursors using the oclose routine. 
  Disconnect from the databases: use ologoff to close an open connection to oracle.  

3.Obsolescent OCI Routines

 After get through the section "Something you should know" ,  you may find some strange 
words : oexec , ologoff  or oclose . There are old routines in preceding release . 
 Release 8.0 of the Oracle Call Interface introduced an entirely new set of functions which 
were not available in release 7.3. Release 8.1 added more new functions. Oracle9i OCI continues 
to support these new functions, and adds more new calls. The earlier 7.x calls are still available, 
but Oracle strongly recommends that existing applications use the new calls to improve performance 
and provide increased functionality.
 To get more information ,  check it in the chapter named "Introduction and Upgrading" in 
OCI document .

4. Introduce to OCI Makefile

 It's time to make out the source file , and the first one is Makefile which is a trunk in a project .
But then it is the end of  a first exploration .

 Notice that the head files of OCI are put in two directories and the lib file is libclntsh.so.9.0 
which is the same as Pro*C .  This is a simple one ,  just copy the code in last article and 
divide into the corresponding files as the list . Then use "make all" or "make clean" to deal with 
the source file automaticly . You would see something like this .

[root@liwei oci]# make clean;
rm -f OCIDB OCIDB.o OCIException.o Exception.o OCIError.o Main.o
[root@liwei oci]# make all;
[OCIDB.o]
---------------------
g++ -g -o OCIDB.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIDB.cpp

[OCIException.o]
---------------------
g++ -g -o OCIException.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIException.cpp

[Exception.o]
---------------------
g++ -g -o Exception.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c Exception.cpp

[OCIError.o]
---------------------
g++ -g -o OCIError.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIError.cpp

[Main.o]
---------------------
g++ -g -o Main.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c Main.cpp

[link] ... 
---------------------
g++ -g -o OCIDB OCIDB.o OCIException.o Exception.o OCIError.o Main.o -L/home/ora/ora9/oracle/lib -lclntsh

 That's good . Take a rest for next step .

-------------------------------------------------------------------------------------------------------

Oracle数据库开发(六).OCI应用初探

草木瓜

2007.6.25  
 
一、序

 在上一次，我提供了一个完整的OCI示例，内容包括数据库连接和SQL操作的实际代码。
当然一个小例子不可能包括所有内容，不过我认为对初学者是一个不错的开始。

 与Pro*C一样，需要确认安装OCI组件，查看下面的路径：
 
 Windows   :   $ORACLE_HOME\oci
 Linux/Unix  :   $ORACLE_HOME/rdbms/demo
 
 这些目录包含一些由ORACLE提供的一些示例。虽然有些杂乱，不过还是一些帮助的。
 我们这里使用的主要平台是Linux。 Windows下怎么设置呢？可以参见《Oracle数据库
开发(一).Windows下配置使用ProC》一文，都是类似的。

二、一些你需要知道的东西

 OCI是什么 ？
 
 OCI是一组底层的API(应用程序接口)，主要和Oracle数据库进行交互。你可以调用一些
操作如 logon , execute, parse, fecth 等等。OCI支持大数据语言，通常使用C/C++。与Oracle
Pro*C等不同，OCI不需要预编译。

 我这里也找着一份关于在Pro*C和OCI之间选择的官方说明。
 
 我应该使用OCI还是Pro*C？
 
 OCI比Pro*C的一些优势：
  
  OCI的性能十分出色
  代码大量缩减
  对内置函数直接访问
  对LONG类型的分段操作(可以处理LONG相关的任何错误)
  Pro*C不能为绑定变量动态分配内存
  不能控制Pro*C自动生成的代码 
  
 OCI开发的一些常见问题：
 
  OCI代码不容易掌握
  ...
  
 OCI开发流程：
 
  连接多个数据库：使用OCILogon (olog, olon or orlon)
  打开游标：oexec, oexn, ofen 或者 oftech
  执行相应SQL语句
  关于游标：oclose
  断开连接：ologoff
  
三、废弃的一些程序标准

 看过上节，你会发现一些奇怪的单词，oexec , ologoff  或 oclose 。这些都是先前版本
旧的OCI标准。

 OCI 8.0 引入一套全新的程序结构，是7.3以前没有的。8.1版本又扩展了一些函数。
在Oracle 9i中虽然支持这些旧的标准，不过Oracle强烈建议使用全新的OCI标准库。
 参考OCI文档中"介绍和升级内容"一节，获取更多信息。
 
四、OCI Makefile 介绍

 现在差不多该介绍源代码了，首先的是Makefile文件，可以说成是整个项目的中心，参
看例中的文件内容。注意头文件目录有两个，库文件和Pro*C使用的一样，还是 libclntsh.so.9.0 ，
相关路径自已调整。
 这个Makefile比较简单，把前面文章罗列的所有代码复制并建立相应文件，使用"make all"
"make clean" 命令，你应该能看到如下类似的内容： 

[root@liwei oci]# make clean;
rm -f OCIDB OCIDB.o OCIException.o Exception.o OCIError.o Main.o
[root@liwei oci]# make all;
[OCIDB.o]
---------------------
g++ -g -o OCIDB.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIDB.cpp

[OCIException.o]
---------------------
g++ -g -o OCIException.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIException.cpp

[Exception.o]
---------------------
g++ -g -o Exception.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c Exception.cpp

[OCIError.o]
---------------------
g++ -g -o OCIError.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c OCIError.cpp

[Main.o]
---------------------
g++ -g -o Main.o -I/home/ora/ora9/oracle/rdbms/demo -I/home/ora/ora9/oracle/rdbms/public -c Main.cpp

[link] ... 
---------------------
g++ -g -o OCIDB OCIDB.o OCIException.o Exception.o OCIError.o Main.o -L/home/ora/ora9/oracle/lib -lclntsh

 Makefile相关知识可以去Google一下，文章从现在开始，就要陆续介绍一些OCI
实质性的内容了。

OCI(Oracle Call Inte***ce)是由头文件和库函数等组成的一套Oracle数据库应用程序编程接口工具，OCI程序实质上就是用高级语言写的程序，其特点是内部含有对OCI子函数库的调用。
OCI程序对开发环境的要求相对较低，只要有C语言的OCI开发工具包和C编译器就可以，程序设计相比PRO*C复杂了点。

1、创建和初始化OCI环境
首先要在源程序中包含OCI头文件：#include <oci.h>
OCI环境即OCI函数的工作环境，在调用其他函数之前必须先调用OCIInitialize()和OCIEnvInit()函数创建和初始化OCI环境，其他OCI函数要在这个环境中才能执行。
先定义变量：
OCIEnv**   m_envhp;
OCIError*  m_errhp;
OCIServer* m_srvhp;
OCISvcCtx* m_svchp;
OCIStmt *  m_stmthp;

OCIInitialize(
               (ub4) OCI_DEFAULT,
               (dvoid *)0,
               (dvoid * (*)(dvoid *, size_t))0,
               (dvoid * (*)(dvoid *, dvoid *, size_t))0,
               (void (*)(dvoid *, dvoid *))0
              );

OCIEnvInit(
            (OCIEnv **)&m_envhp,
            OCI_DEFAULT, (size_t)0,
            (dvoid **)0
           );

其中m_envhp为输出参数，是一个指向OCI环境句柄的指针，OCI_DEFAULT 是OCI环境的初始化模式。OCIEnvInit()函数中的size_t类型变量为分配给用户的内存数量，dvoid **类型变量指向用户的内存区域，该区域的大小等于size_t类型变量。
OCI函数中，大量使用OCI定义的数据类型和宏，其定义可参考$ORACLE_HOME/rdbms/demo目录下的oci.h头文件。

2、申请句柄
句柄是指向OCI库所分配的内存区域的指针，该内存区域中的数据由OCI库维护，应用程序可通过句柄访问其中的数据。下面是应用程序中最常用的几个句柄：
OCIHandleAlloc(
                (dvoid *)m_envhp,
                (dvoid **)&m_errhp,
                 OCI_HTYPE_ERROR,
                (size_t)0,
                (dvoid **)0
               );

OCIHandleAlloc(
                (dvoid *)m_envhp,
                (dvoid **)&m_srvhp,
                OCI_HTYPE_SERVER,
                (size_t)0,
                (dvoid **)0
              );

OCIHandleAlloc(
                (dvoid *)m_envhp,
                (dvoid **)&m_svchp,
                 OCI_HTYPE_SVCCTX,
                (size_t) 0,
                (dvoid **)0
              );

OCIHandleAlloc(
                (dvoid *)m_envhp,
                (dvoid **)&m_stmthp,
                 OCI_HTYPE_STMT,
                (size_t)0,
                (dvoid **)0
               );

其中m_errhp为新申请的句柄，m_envhp为它的父环境句柄，OCI_HTYPE_ERROR为句柄类型，表示这是一个错误报告句柄，OCI_HTYPE_SERVER表示服务器句柄，OCI_HTYPE_SVCCTX表示服务环境句柄，OCI_HTYPE_STMT表示语句句柄。

存储在句柄中的数据称为句柄属性，所有OCI句柄都具有属性，可以调用OCIAttrGet()和OCIAttrSet()函数来读取、设置句柄属性。

3、连接服务器建立会话
首先调用
OCIServerAttach(m_srvhp, m_errhp, (text *)"", strlen(""), OCI_DEFAULT);
函数建立与指定服务器的连接，text *类型变量为空，表示连接默认数据库服务，OCI_DEFAULT表示应用程序的操作模式为阻塞模式，在这种方式下，只有当OCI调用完成后才将控制权返回给客户端应用程序。

然后调用
OCILogon(m_envhp,m_errhp, &m_svchp, (text*)m_szUser,strlen(m_szUser), (text*)m_szPassword, strlen(m_szPassword), (text*)m_szDbName, strlen(m_szDbName));
建立数据库会话。此函数隐含申请服务器句柄和用户会话句柄，登录后，句柄是只读的，不能再设置句柄属性。

4、执行SQL语句并处理数据
将要执行的SQL语句copy到szSqlStr字符串中:
snprintf( szSqlStr, sizeof(szSqlStr), "select PASSWORD from USERS where USERNAME=’chen’ ");
执行下列语句：

OCIStmtPrepare(m_stmthp, m_errhp, (text*)szSqlStr, (ub4) strlen(szSqlStr), (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT); //准备SQL语句

OCIDefine *defnp0 = (OCIDefine *) 0; //定义输出变量

OCIDefineByPos( m_stmthp, &defnp0, m_errhp, 1, (dvoid *)szUSERNAME, 100, SQLT_STR, (dvoid *) 0, (ub2 *)0, (ub2 *)0, OCI_DEFAULT); //绑定变量

OCIStmtExecute( m_svchp, m_stmthp, m_errhp, (ub4) 1, (ub4) 0, (OCISnapshot *) NULL,(OCISnapshot *) NULL, (ub4) OCI_DEFAULT); //执行SQL语句

5、结束会话断开数据库连接
OCILogoff( m_svchp, m_errhp );

6、断开与数据源的连接，释放句柄
OCIServerDetach( m_srvhp, m_errhp, OCI_DEFAULT ); //断开与数据源的连接
OCIHandleFree((dvoid *) m_stmthp, OCI_HTYPE_STMT); //释放句柄
OCIHandleFree((dvoid *) m_svchp, OCI_HTYPE_SVCCTX);
OCIHandleFree((dvoid *) m_srvhp, OCI_HTYPE_SERVER);
OCIHandleFree((dvoid *) m_errhp, OCI_HTYPE_ERROR)
3.7生成可执行文件（两种方法）
(1)同普通的C程序：
   gcc -o exampled –I. –I$(ORACLE_HOME)/precomp/public example.c

(2)利用Oracle自带的Make文件：
首先将$ORACLE_HOME/rdbms/demo/demo_rdbms.mk文件copy到OCI源程序所在的目录，将源文件编译为目标文件：
#gcc –c example.o -I$(ORACLE_HOME)/rdbms/demo -I$(ORACLE_HOME)/network/public -I$(ORACLE_HOME)/rdbms/public/ example.c
然后用命令：#make -f demo_rdbms.mk build OBJ*=**ample.o EXE=exampled，exampled就为生成的可执行文件