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类型的成员变量。