OTL翻译(6) -- otl_connect类

otl_connect

这个类封装了连接的功能，如连接、断开连接、提交、回滚等。otl_connect也就是一个用来创建连接对象并进行管理的类。

序号

方法、变量

说明

1

int connected

数据库是否已经连接的标志。

该标志只是在数据库连接成功后才标志为1（成功）。如果一个已经连接成功数据库的连接在长时间没有数据库操作的情况下，由数据库主动断开了连接，该标志不会改为。还是为1（真），所以为了保证该标志一直有效，需要为该标志建一个“心跳”，以判断数据库是否仍旧连接为真。如发送一个简单的SELECT　CURRENT TIME FROM DUAL的请求。

2

static int otl_initialize(const int threaded_mode = 0)

用于初始化OTL连接库的环境的静态函数。它仅需要在程序首次连接数据库之前调用一次即可。threaded_mode参数是为了表明是否在多线程的环境下运行。但是OTL并不保证线程安全，因为OTL里面不提供任何的线程锁或临界区。

threaded_mode = 1：多线程

threaded_mode = 0：单线程

3

static int otl_terminate(void)

用于中止ORACLE OCI８、９的数据库环境。它需要在程序最后连接数据库连接后被执行一次。

该函数仅是对OCITerminate()函数的一个简单封装。在多线程环境里面，为了能够把主线程从数据库断开，该函数必须被调用，因为它会释放一些客户端并且处理其他的一些事情。

4

void cancel(void)

仅用于OCI8/9/10/11版本。

用于中断SQL语句的执行。或者说从一个线程里面异步的中断一个正在执行中的线程。对于被中止的线程中将会返回一个“user requested cancel the current operation”异常。

5

void change_password(…)

序号	参数	说明
1	const char * user_name	用户名
2	const char * old_password	旧密码
3	const char * new_password	新密码

仅用于OCI8/9/10/11版本。

更改ORACLE用户的密码。程序必须在连接在ORACLE服务端的时候被调用。

6

void set_transaction_isolation_level(const long int level)

仅用于DB2 CLI和ODBC。

设置事务的隔离级别。该方法允许用户设置事务为：读提交、读未提交、可重复读、可串行化。更多的事务隔离请见数据库手册。

OTL为事务级别定义了如下常变量

otl_tran_read_uncommied

otl_tran_read_commited

otl_tran_repetable_read

otl_tran_serializable

7

void set_max_long_size(const int amax_size)

为大对象设置最大的缓冲区大小。如：varchar_long/raw_long/clob/blob对象。该函数仅用于扩大缓冲区大小的时候使用。默认的大小为：32767.

8

int get_max_long_size(void)

取得大对象的缓冲区大小。

9

void set_cursor_type(const int acursor_type = 0)

该函数仅用于DB2 CLI和ODBC，但也可以对OCI有些影响。一旦设置好了某个类型后，通过该连接的所有的otl_stream流的SQL操作都会被影响。

支持的游标类型如下（详细的请见ODBC或DB2 CLI手册）：

SQL_CURSOR_FORWARD_ONLY(DEFAULT SETTING)

SQL_CURSOR_STATIC

SQL_CURSOR_KEYSET_DRIVEN

SQL_CURSOR_DYNAMIC

10

void set_timeout(const int atimeout = 0)

仅适用于ODBC，对OCI或DB2 CLI没有作用。

用于设置连接的超时时间，一旦设置后，通过该连接的所有的SQL语句都将受影响。单位为秒。

在OCI里面也可以通过另外一种方式实现该功能，如通过一个线程进行SQL操作，另一个线程作计时，如果时间到了，SQL还未执行完成，则调用calcel()函数强制中断。

在DB2 CLI里面类似上面的方式也可以用，只是把otl_connect::cancel()换成otl_stram::cancel()即可。

在将来，如果OCI或DB2 CLI支持该功能，那么该函数将会被复用。

11

otl_connect(const char * connect_str,const int auto_commit = 0)

构造函数。

创建一个OTL连接对象，并调用rlogon()函数。

12

void rlogon(…)

序号	参数	说明
1	const char * connect_str	数据库连接串
2	const int auto_commit=0	是否自动提交标志

连接数据库。

对于OCI、ODBC和DB2 CLI都有不同格式的连接串。

OCI：

USERNAME/PASSWORD(对本地数据库)

USERNAME/PASSWORD@TNS_NAME(远程数据库通过SQL*NET)

ODBC和DB2 CLI

USER/PASSWORD@DSN(类ORACLE格式)

DSN=VALUE;UID=VALUE;PWD=VALUED(ODBC格式)

在某些情况下，密码还可能包括有@符号，如果需要增加该符号，则需要通过”\”标志进行转义。

auto_commit标志是用来设置连接的自动提交标志。它意味着，每执行一个SQL语句，都将会自动提交该事务。但是与otl_stream里面的自动提交是两码事。如果需要设置自动提交，则将该参数设置为1,否则默认为0（不自动提交）。

在ORACLE7、ODBC或DB2 CLI版本里面，自动提交意味着每执行完都提交，但是在ORACLE8及以后版本里面，该标志则是执行成功后才提交。

13

void rlogon(Lda_Def * lda)

连接到某个第过第三方库或嵌入式SQL连接的数据库里面。该函数仅用于OCI７。详细请见例：58

14

void rlogon(…)

序号	参数	说明
1	HENV henv	数据库环境句柄
2	HDBC hdbc	数据库连接句柄
3	const int auto_commit = 0	自动提交标志

通过其他的ODBC或第三方库连接数据库。它仅用于ODBC或DB2 CLI。

15

void rlogon(…)

序号	参数	说明
1	const OTL_UNICODE_CHAR_TYPE * username	用户名
2	const OTL_UNICODE_CHAR_TYPE * password	密码
3	const OTL_UNICODE_CHAR_TYPE * dsn	数据源名称
4	const int auto_commit = 0	自动提交标志

仅用于ODBC或DB2 CLI。必须定义OTL_UNICODE_EXCEPTION_AND_RLOGON宏。

连接数据库。该函数在定义了UNICODE情况下使用，它能够通过UNICODE的用户名和密码连接数据库。

16

otl_connect(…)

序号	参数	说明
1	HEVN henv	数据库环境句柄
2	HDBC hdbv	数据库连接句柄
3	const int auto_commit=0	自动提交标志

仅适用于ODBC或DB2 CLI。

通过ODBC或第三方库进行数据库连接。

17

void rlogon(…)

序号	参数	说明
1	OCIEnv *envhp	指向通过SQLEnvGet()函数获得的返回值的指针。
2	OCISvcCtx*svchp	指向通过SQLSvcCtxGet()函数返回的结果的指针

仅适用于OCI8i/9i/10g/11g。

通过PRO*C或第三方库连接数据库。它必须在定义了OTL_ORA8_PROC宏的情况下使用。

18

void rlogon(…)

序号	参数	说明
1	const char * connect_str	数据库连接串
2	const int auto_commit = 0	自动提交标志
3	const char * xa_server_external_name = 0	XA外部服务器名
4	const char * xa_server_internal_name = 0	XA内部服务器名
5	bool threaded_mode = false	需要定义宏OTL_ORA_OCI_ENV_CREATE

仅适用于OCI8/8i/9i/10g/11g。

连接数据库，并且设置XA库需要的的外部和内部连接名。

19

void logoff()

断开数据库连接。

如果OTL是通过PRO*C或第三方库连接的数据库，则么该函数只是断开与PRO*C的关系，而不是实际上断开数据库连接。

20

void server_attach(…)

序号	参数	说明
1	const char * tnsname = 0	TNS名
2	const char * xa_server_external_name = 0	XA服务器外部名
3	const char * xa_server_internal_name = 0	XA服务器内部名
4	bool threaded_mode = false	需要定义宏OTL_ORA_OCI_ENV_CREATE

仅适用于OCI8/8i/9i/10g/11g。

该函数为对ServerAttach()函数的封装。主要功能是开始一个session，结合session_begin()和sessin_end()使用。主的优点在于相比于传统的连接池，性能更佳。tnsname主要是用来连接远程服务器的，对于本地服务默认可以设置为0.

21

void server_detach()

仅适用于OCI8/8i/9i/10g/11g。

断开ORACLE连接。

22

void session_begin(…)

序号	参数	说明
1	const char * username	用户名
2	const char * password	密码
3	const int auto_commit = 0	自动提交标志
4	const int session_mode = OCI_DEFAULT	OCI_SYSDBA:在这种模式下，采用SYSDBA方式认证； OCI_SYSOPER：这种模式下采用SYSOPER方式认证。

仅适用于OCI8/8i/9i/10g/11g。

开始一段数据库的SESSION，主要功能在于通过attach/detach函数来开始一个SESSION。主要的目的在于通过SESSION来执行一系列的函数比传统的连接池执行起来性能上要快不少。

23

void session_end()

仅适用于OCI8/8i/9i/10g/11g。

结束一个ORACLE的SESSION

24

void session_reopen(…)

序号	参数	说明
1	const int aauto_commit = 0	session的自动提交标志

仅适用于OCI8/8i/9i/10g/11g。

重新打开一个已经被session_end()关闭过的session。重新打开一个已经关闭过的session的优点在于，重新打开速度上要快5－10%。因为用户名和密码在前面的session_begin()里面已经初始化过，所以不需要重新再处理。

详细请见例：61

25

void commit()

提交一个事务。

对于ORACLE/ODBC/DB2 CLI来说，默认的自动提交为否，那么对于所有执行过的事务都需要手工的调用该函数进行事务提交。

如果设置了自动提交，则不需要再调用该函数。

26

void commit_nowait()

在定义了宏OTL_ORA10_R2或OTL_ORA11G宏下有用。

异步提交。仅适用于ORACLE10.2及以后版本。

27

void rollback()

回滚当前事务。

28

void auto_commit_off()

void auto_commit_on()

设置自动提交为开或关。对连接或SESSION都有效。

注：该函数仅部分的向后兼容。

29

void set_stream_pool_size(const int max_size = otl_max_default_pool_size)

设置otl_stream的缓冲区大小。使用该函数必须定义OTL_STREAM_POOLING_ON、OTL_STL或OTL_ACE宏。

如果OTL_STREAM_POOLING_ON宏定义了，该函数体才被包含进代码里面。同时，一个默认的流缓冲区将被作为otl_connce一部分自动分配。然后如果调用了这个函数，那么先前分配的将会被释放，然后进行重新分配。

30

void set_character_set(const int char_set = SQLCS_IMPLICIT)

仅适用于定义了OTL_UNICODE宏的ORACLE　OCI8i/9i/10g/11g环境。

SQLCS_IMPLICIT：数据库默认的字符集

SQLCS_NCHAR：数据库国际字符集

当使用了VARCHAR2/CHAR/LONG/CLOB类型的时候，则需要默认的字符集；当使用了NVARCHAR2/NCHAR/NCLOB字段类型的情况下，则需要设置为国际字符集。

SQLCS_IMPLICIT/SQLCS_NCHAR是在ORACLE的OCI头文件里面被定义的。

一旦该函数设置了字符集，那么所有的通过该函数设置过的otl_connect连接的流都将使用该字符集。

在使用了UNICODE后，字符的定义也将被一同进行了扩展。如CHAR[20]代表的是容纳一个双字节的19个字符，还加上两个字节的空字符。这样做的主要目的是为了跟数据库里面兼容。

31

void set_throw_on_sql_success_with_info(const bool throw_flag = false)

仅适用于ODBC和DB2 CLI。必须定义宏OTL_THROW_ON_SQL_SUCCESS_WITH_INFO。

在定义了该标志为真为，对于执行SQLExecDirect()/SQLExecute()函数成功后，仍抛出一个异常。这对某些需要获取更多信息的执行非常有帮助。如调用一个存储过程。

32

otl_connect & operator<<(const char * str)

往otl_connect对象写入一个字符串。如果该对象未连接至数据库，那么该字符串将被作为连接的用户名密码格式被otl_connect对象用来连接数据库；

如果已经连接成功数据库，则该字符串将被作为SQL语句立刻被执行。

33

otl_connect & operator<<=(const char *str)

往otl_connect对象写入字符串，该字符串其实就是一个将要被otl_stream执行的SQL语句。

34

otl_connect & operator>>(otl_stream & s)

把通过otl_connect<<=()传进来的SQL语句交给otl_stream执行。如果没有传入的SQL语句，那么将会抛出一个“***INVALID COMAND ***”异常。

35

long direct_exec(…)

序号	参数	说明
1	const char * sqlstm	SQL语句
2	int ignore_error = otl_exception::enabled	忽略错误标志

执行一段不带占位符的SQL语句，返回该语句执行的记录数。

该函数返回下面两种情况的返回值：

-1：如果异常被关闭了，但是数据库API返回一个错误。

>=0：如果SQL执行成功。

36

void syntax_check(const char * sqlstm);

检查SQL语句，如果有错误则会抛出一个异常。

37

void set_connection_mode(const int connection_mode)

在定义了OTL_ODBC_MULTI_MODE宏的情况下，OTL可以通过不用定义相关数据为的宏，而通过ODBC进行多种数据库连接。

它必须在数据库连接之前进行调用。

下面这些OTL定义的常量为OTL支持的数据库连接类型。

OTL_DEFAULT_ODBC_CONNECT：等同于设置了OTL_ODBC宏。下面的这些数据库都可以进行连接DB2/FIREBIRD/INFORMIX/MS ACCESS/ORACLE/SAP/MAXDB/SQLITE/SYBASE/其它兼容ODBC数据库的数据库。

OTL_TIMESTEN_ODBC_CONNECT：

OTL_MSSQL_2005_ODBC_CONNECT：

OTL_POSTGRESQL_ODBC_CONNECT：

OTL_ENTERPRISE_DB_ODBC_CONNECT：

OTL_MYODBC35_ODBC_CONNECT：

OTL_MSSQL_2008_ODBC_CONNECT：

38

int get_connection_mode()

仅在定义了OTL_ODBC_MULTI_MODE宏情况下适用。

取得数据库连接类型。

39

void set_prog_name(const char * prog_name)

仅适用于OTL_DB2_CLI宏定义了的情况下。

设置程序的名称，该名称是在数据库“list application”命令调用时候显示的名称。它必须在连接之前调用。如下：

otl_connect db;

db.set_prog_name(“myapp”);

db.rlogon(“usr/pass@db”);