Oracle Database/Oracle C++ Call Interface（OCCI）

添加链接
维基教科书，自由的教学读本

OCCI是一套用于访问Oracle数据库的C++ API。设计目的是提供一个小的良好封装的类与界面的集合，易于使用。大量特性服务于关系访问（类似于JDBC）、对象关系访问与伸缩性。完全支持SQL/PLSQL执行。支持所有Oracle数据类型与大对象（LOB）类型。支持数据库的元数据访问。

API需要包含的头文件与库文件[编辑]

头文件occi.h（以及隐式使用occiCommon.h，occiControl.h，occiData.h，occiObjects.h）。库文件oraocci12.lib或oraocci12d.lib，必须对应Release与Debug版本。使用的dll包括oci.dll、oraocci12d.dll、oraociei12.dll、oraons.dll。

以上均包含在Oracle Instant Client中。

Environment类[编辑]

Environment实例指出：

  • 应用程序模式：OBJECT/THREADED/MUTEXED
  • 对象cache设置
  • OCCI类的内存堆

可以创建“连接池”： createConnectionPoll 示例： 

Environment *env;
env = Environment::createEnvironment(Environment::DEFAULT);

//查看客户端版本号：
int majorVersion, minorVersion,updateNum,patchNum,portUpdateNum;
Environment::getClientVersion(majorVersion, minorVersion, updateNum, patchNum, portUpdateNum);

数据类[编辑]

OCCI定义了一些数据类，如Number,Date,IntervalYM,Timestamp，Bytes，以方便对Oracle数据类型的支持。为支持大对象，定义了类Bfile，Clob，Blob。

PObject类[编辑]

PObject类包含以下方法：

  • fush();
  • Connection *getConnection();从一个实例化的永久对象中返回连接。
  • isLocked();判断永久对象是否被锁（TRUE或FALSE）。
  • isNull();判断永久对象是否为空（TRUE或FALSE）。
  • Lock(PObject::LockOption lock_option);在数据库中锁住一个对象，其中lock_option取值为OCCI_LOCK_WAIT、OCCI_LOCK_NOWAIT。
  • markDelete();删除数据库中的永久对象。
  • markModified();修改永久对象。
  • PObject &operator(constPObject &obj);赋值（对象）。
  • operator delete(void*obj,size_t size);删除对象，但不能删除数据库中的对象。
  • *operator new(size_t size);创建临时对象。
  • *operator new(size_t size,constConnection *x,const string &tablename,const char *type_name);创建永久对象。
  • pin();
  • setNull();设置对象为空。
  • unmark();不标记永久对象为删除或修改。
  • unpin(UnpinOption mode);其中，mode的取值为OCCI_PINCOUNT_RESET、OCCI_PINCOUNT_DECR。

SQLException类[编辑]

SQLException类提供错误代码及其错误信息，包含以下方法： getErrorCode();返回数据库中的错误编码。 getMessage();返回错误信息，没有则为空。

Connection类[编辑]

  • Commit();提交事务。 
  • createStatement
  • flushCache(); 
  • rollback();事务的回滚。 
  •  terminateStatement

示例： 

Connection *conn;
//char connstr[256]=R"(//Server_IP_Addr:1521/Database_Name)";
conn = env->createConnection(UserName, Password, connstr);

//查看服务器版本：
std::string serverVer = conn->getServerVersion();

ConnectionPool类[编辑]

  • ConnectionPoll类提供了C++程序与指定数据库间的连接池，包含以下方法：
  • createConnection(const string&username,const string &password);创建一个连接。
  • getBusyConnections();返回连接池中被占用的连接数量。
  • getMaxConnections();返回连接池的最大连接数。
  • getMinConnections();返回连接池的最小连接数。
  • getOpenConnections();返回连接池中已经被打开的连接数。
  • getPollName();返回连接池的名称。
  • getTimeOut();返回连接池的超时时间。
  • setErrorOnBusy();设置异常，当连接池处于繁忙或达到最大连接数后。
  • serPoolSize(unsigned intminConn,unsigned int maxConn,unsigned int incrConn);设置连接池的大小，其中参数minConn是最小连接数，maxConn是最大连接数，incrConn是递增连接数。
  • setTimeOut();设置超时时间。
  • terminateConnection(Connection *conn);断开连接。

Statement类[编辑]

Statement对象

  • execute：执行任何SQL语句，返回状态
  • executeUpdate：返回Insert/Update/Delete的行数
  • executeQuery：返回ResultSet
  • executeArrayUpdate(unsigned intarrayLength);同时修改多条记录，前面必须使用了setDataBuffer()方法设置一个数量或设置了一个流（stream）。

可以使用形如:1、:2这样的占位符，用setXXX成员函数绑定参数。用getXXX成员函数返回参数。isNull判断第X个值是否为空。isTruncated判断第X个值是否被截取。

对DML（INSERT/UPDATE/DELETE）,可以一次操作多行：

  • SetMaxIterations:设置最多的行数
  • SetMaxParamSize：设置某个字符串参数的长度上限
  • addIteration：增加一行数据的绑定

执行PL/SQL的函数/过程/block时，用setXXX绑定参数，setNull某参数设置为空。用registerOutParam指出输出参数并用setMaxParamSize指出尺寸，用getXXX获取输出参数的值。执行execute。

批量处理非查询语句时，首先必须使用stmt->setMaxIterations(unsigned int maxnum)方法设置最大的批处理数；然后使用setMaxParamSize(unsignedint paramindex,int paramsize)方法设置对应参数的大小，对于有固定长度的参数可以不必重新设置，如int,double；然后绑定参数使用setXXX()方法，每循环一次必须使用stmt->addIteration()方法，再进行下一次循环，直到最后一次。

其它函数：

  • addIteration();增加一个循环。
  • closeResultSet(ResultSet *rs);关闭一个结果集。
  • closeStream(Stream *stream);关闭一个已定义的流。
  • getAutoCommit();返回是否事务自动提交。
  • getResultSet();得到一个结果集（ResultSet）。
  • getSQL();返回当前的SQL语句。
  • getUpdateCount();返回被更新的数量。
  • setAutoCommit(bool autocommit);设置事务是否自动提交。
  • setSQL(const string &sql);设置一个SQL语句。
  • Status();返回当前的状态。

ResultSet类[编辑]

ResultSet对象：

属性Status：取值为DATA_AVAILABLE、STREAM_DATA_AVAILABLE、END_OF_FETCH

对所有类型获取/设置值的统一方法：

  • setXXX：Statement对象
  • getXXX：Statement对象与ResultSet对象

也可以使用流方式绑定/获取数据：

  • setCharacterStreamMode：结果集中设定流模式
  • getStream：结果集的当前行建立一个流对象
  • readBuffer: 流对象拷贝数据到缓冲区

用户数据缓冲区可以极小化数据拷贝。

  • -数组DML：Statement:executeArrayUpdate(int nRows), Statement::setDataBuffer
  • -数组获取：ResultSet::next(int nRows), ResultSet::setDataBuffer

其他函数：

  • cancel();取消结果集。
  • closeStream(Stream *stream);关闭一个流。
  • getMaxColumnSize(unsigned intcolIndex);返回某列包含的数据量。
  • getRowid(unsigned intcolIndex);返回rowid值。
  • isNull(unsigned int colIndex);判断值是否为空。
  • isTruncated(unsigned intcolIndex);判断值是否被删

对象-关系数据库特性[编辑]

支持Oracle对象-关系数据库特性。包括对象表（Object table)或对象类型列(object type columns)。OTT可支持生成相应的C++类的源文件。

支持Oracle的VARRAY与Nested Table数据类型

MetaData[编辑]

通过MetaData对象，对数据库对象（表、过程、类型等）与查询结果的MetaData访问。

Oracle Advanced Queue[编辑]

国际化[编辑]

国际化支持方面，Environment::createEnvironment(string charset, string ncharset)；client characterset用于CHAR类型。National characterset用于NCHAR类型。

查询数据库CHAR类型与NCHAR类型的具体定义： 

SELECT
    *
FROM
    nls_database_parameters
WHERE
    PARAMETER IN(
        'NLS_CHARACTERSET',
        'NLS_NCHAR_CHARACTERSET'
    );

例如, 

Environment::createEnvironment("ZHS16GBK", "OCCIUTF16")；//"AL16UTF16"

应通过setDatabaseNCHARParam()先把Statement实例的某个参数设为NCHAR/NVARCHAR类型，然后setUString()绑定参数。

UString数据类型表示UCS-2编码字符串。所有成员函数都有UString的重载版本。在Windows平台，UString等价于std::wstring数据类型。对于Unicode应用程序，OTT产生的CHAR/VARCHAR属性为UString类型的成员变量。

取自“https://zh.wikibooks.org/w/index.php?title=Oracle_Database/Oracle_C%2B%2B_Call_Interface（OCCI）&oldid=128391”