OTL翻译(4) -- otl_stream类

最新推荐文章于 2021-01-19 04:04:47 发布

lhw_1

最新推荐文章于 2021-01-19 04:04:47 发布

阅读量3.1k

点赞数

文章标签： stream sql 数据库 oracle 存储 exception

otl_stream

Otl_stream是具体实现otl_stream_concept的类。任何的SQL语句、SQL语句块和存储过程都能通过otl_stream进行处理。

传统的数据库API处理SQL语句的时候，需要绑定变量与占位符，因此，程序员需要定义变量、解析SQL语句、调用绑定占位符的函数、把变量绑定到占位符上、执行SQL、读取输出的变量等等。如此循环。以上所有的这些操作在OTL里面的otl_stream类里面都是自动处理的，otl_stream类提供了与数据库交互自动化最大性能。该性能仅取决于一个参数－缓冲区大小。缓冲区是用于存放SQL执行过程中的逻辑行数。

注：在timesten7.0.2或以上版本的数据库中，定义了OTL_TIMESTEN_UNIX或OTL_TIMESTEN_WINDOWS宏的时候，缓冲区大小可以设置为０。此时表示默认使用数据库的最佳缓冲区大小。一般情况下是一个元素大小。具体更多信息请参考数据库的手册。

一个SQL语句在otl_stream里面至少需要一个输入或输出占位符，对于没有占位符的SQL语句，它将被作为常量的SQL语句作为另一种方式执行。

从OTL4.0.115版本开始后，缓冲区大小的类型为整形，以前的版本全是短整形。如果需要支持旧版本的代码，请在编译代码前添加定义OTL_STREAM_LEGACY_BUFFER_SIZE_TYPE宏。

Otl_stream类有如下的公共方法：

序号

函数名

说明

otl_stream(…)

序号	参数	说明
1	const int arr_size	缓冲区大小
2	const char * sqlstm	SQL语句或SQL语句块
3	otl_connect & db	otl_connect对象
4	const char * ref_cur_placeholder = 0	如果otl_stream返回一个游标，则该参数指定游标的占位符
5	const char * sqlstm_label = 0	sql语句标识，如果指定了该参数，则会用sqlstm_label填充otl_exception::stm_text，并且原来的SQL语句将不可见。

仅ORACLE　7/8/9/10/11版本

构造函数。该构造函数创建一个otl_steram对象，并且调用open()函数。

otl_stream(…)

序号	参数	说明
1	const int arr_size	缓冲区大小
2	const char * sqlstm	SQL语句或SQL语句块
3	otl_connect & db	otl_connect对象
4	const int implicit_select = otl_explicit_select	如果otl_stream返回一个存储过程的结果集，该参数必须指定为otl_implicit_select
5	const char * sqlstm_label = 0	sql语句标识，如果指定了该参数，则会用sqlstm_label填充otl_exception::stm_text，并且原来的SQL语句将不可见。

仅ODBC/DB2 CLI

构造函数，该构造函数创建一个otl_stream对象，并且调用open()函数。

在ODBC和DB2 CLI下面对该对象还定义了如下两个常量：

otl_explicit_select:指定该流为一个简单的SELECT语句流；

otl_implicit_select:指定该流为一个返回结果集的流；

void open(…)

序号	参数	说明
1	const int arr_size	缓冲区大小
2	const char * sqlstm	SQL语句或SQL语句块
3	otl_connect & db	otl_connect对象
4	const char * ref_cur_placeholder = 0	如果otl_stream返回一个游标，则该参数指定游标的占位符
5	const char * sqlstm_label = 0	sql语句标识，如果指定了该参数，则会用sqlstm_label填充otl_exception::stm_text，并且原来的SQL语句将不可见。

仅ORACLE　7/8/9/10/11版本

该函数打开（执行）SQL语句，总共分为如下：解析SQL语句、在流内部为输入输出变量分配内存空间、自动绑定变量到对应的占位符。

void open(…)

序号	参数	说明
1	const int arr_size	缓冲区大小
2	const char * sqlstm	SQL语句或SQL语句块
3	otl_connect & db	otl_connect对象
4	const int implicit_select = otl_explicit_select	如果otl_stream返回一个存储过程的结果集，该参数必须指定为otl_implicit_select
5	const char * sqlstm_label = 0	sql语句标识，如果指定了该参数，则会用sqlstm_label填充otl_exception::stm_text，并且原来的SQL语句将不可见。

仅ODBC/DB2 CLI

该函数打开（执行）SQL语句，总共分为如下：解析SQL语句、在流内部为输入输出变量分配内存空间、自动绑定变量到对应的占位符。

int eof()

测试流里面是否所有的数据全被读取出来，该函数与C++的IO流里面的eof()函数同理。

int setBufSize(const int buf_size)

设置缓冲区大小。该函数仅是对后续的otl_connect::operator>>(otl_stream&)操作保存（新建）一个新的缓冲区。

void flush()

刷新输出流缓冲区。它实际上的操作是通过执行流里面的SQL语句来填充输出缓冲区。流在缓冲区满的情况下自动的进行刷新操作。该函数与C++的IO流的flush()同理。

如果在设置了auto-commit标识的情况下，在刷新了输出缓冲区后，也就会自动的进行一次事务提交。更详细的解释请见set_commit()

void flush(…)

序号	参数	说明
1	const int row_offset = 0	指定刷新缓冲区的行数
2	const bool force_flush = false	忽略以前的错误强制刷新

在OCI8/8i/9i/10g/11g的版本里面还带有一个带两个参数的flush()版本的函数。该函数有两方面的作用：

１、对大数据量的操作更高效

２、能够识别（发现）出重复的数据，并抛出异常

int get_auto_commit_flag()

取得自动提交标识。

1:表示自动提交标识已设置

0:表示自动提交标识未设置

int get_stream_type()

仅ORACLE　7/8/9/10/11版本

取得流的类型。返回的类型由如下的整形常量：

otl_no_stream_type—流还未通过SQL进行实例化

otl_select_stream_type—流是一个简单的SELECT语句的流

otl_inout_stream_type—流是通过一个带有输入输出参数的匿名的SQL块进行实例化的，还有可能是一个存储过程。

otl_refcur_stream_type—流是通过一个SQL语句块进行实例化的，该SQL块返回的是一个游标。在这种流的情况下，只能有输入参数，输出参数一定是一个游标。

otl_constant_sql_type—该类型本只能在使用create_stored_proc_call()里面使用，然而它代表了一种流类型。在create_stord_proc_call()里面它本义也是指不带有参数的，而且它必须通过otl_cursor::direct_exec()执行。

otl_mixed_refcur_stream_type—只由create_stoerd_proc_call()实例的类型。它能够带有输入或输出参数，并且一定有返回一个游标。如果create_stored_proc_call()的sql_stm参数设定了的情况下，流的缓冲区大小必须设置为1，并且必须通过otl_refcur_stream去读取游标的数据。更详细的请见例：153

static void create_stored_proc_call(…)

序号	参数	说明
1	otl_connect& db	otl_connect对象
2	otl_stream & args_strm	otl_stream的外部实例。意思是函数外部的一个变量。为了保证函数能从数据字典表里面取得数据库的信息，该变量必须通过“SELECT … FROM ALL_ARGUMENTS …”来实例化。该变量实例化一次就可以以后续的函数里多次使用。
3	chat * sql_stm	输出参数。带有参数的存储过程名，或兼容otl_stream的SQL语句块。
4	int & stm_type	输出参数，otl_stream的类型
5	char * refcur_placeholder	输出参数。如果存储过程返回一个游标，则该参数保存游标的名字。后面可以被otl_stream::otl_stream()/otl_stream::open()使用。
6	const char * proc_name	存储过程名
7	const char * package_name	存储过程所在的包的名字
8	const char * schema_name = 0	存储过程和包所在的模式名（用户名）
9	const bool schema_name_include = false	指定调用的存储过程名里面是否带有模式（用户）名。
10	const int varchar_size = 2001	存储过程里面的VARCHAR类型的参数是没有大小的。该参数指定VARCHAR参数的大小。
11	const int all_num2type = otl_var_double	该参数定义了NUMBER类型参数如何对应绑定变量
12	const int refcur_buf_size = 1	在存储过程返回游标的情况下，该参数指定游标缓冲区大小。该参数此时对性能影响较大。

仅ORACLE　7/8/9/10/11版本

不能定义在OTL_UNICODE宏下面实现。通过存储过程名去实现一个兼容的otl_stream流。

这是个静态的函数，意图去实现调用oracle的存储过程。

为了能够获取到存储过程的参数和类型，该函数使用ORACLE的系统数据字典。可能会抛出32014、32015、32016的OTL异常。

该函数能够调用下列的函数或存储过程:

1:当前或指定用户名下面的SQL包的存储过程或函数；当前或指定用户名下面的全局的存储过程或函数。

2:公共或私有同义词下面的SQL包的存储过程或函数；公共或私有同义词下面的全局的存储过程或函数。

3:没有重载（同名）的存储过程或函数。

4:带有标量的输入或输出参数，或带有输出游标的存储过程或函数。

void clean(const int clean_up_error_flag = 0)

在不刷新缓冲区的情况下，清理掉缓冲区里面的内容。

如果clean_up_error_flag参数设置为1，那么除了清掉缓冲区内容的同时，还清理掉流里面抛出的异常信息。详细请见例：65、66、67.该参数的意义在于提供一个不需要关闭流的情况下可以重新返回数据库的相关错误信息。

在4.0.6及以后的版本中，该函数还能中断一个正在执行中的SQL语句，并且清空错误信息。

void rewind()

重新处理一个流（恢复一个流到初始状态）。如果该流没有参数，则强制该流的执行。

operator int()

把流转换为int类型的重载操作符。它返回!eof()的结果状态。它能够被用在一直循环里面，如下：

while(s>>f1>>f2){
cout<<"f1="<<f1
    <<", f2="
      <<f2<<endl;
  }

void cancal()

仅ODBC / DB2 CLI。

中止一个正在处理中的SELECT语句或是存储过程。而且对于一个线程中正在运行的，另一个线程能异步的中止该正在执行中的流。

具体的中止操作取决于数据库层的API函数。并且错误信息也是由数据库层抛出。

OCI8/8i/9i/10g也有一个相类似的函数otl_connect:cancel()，但是与DB2 CLI确是不同的。

bool get_next_diag_rec(…)

序号	参数	说明
1	short int & rec_ndx	动态记录的索引
2	SQLCHAR *sqlstate_buf	SQL状态缓冲区，在unicode情况下，该参数类型为SQLWCHAR
3	SQLCHAR * msgbuf	消息缓冲区，在unicode情况下，参数类型为SQLWCHAR
4	short int msg_buf_size	消息缓冲区大小
5	int & native_error	本机错误

仅支持ODBC。

必须定义OTL_ODBC_SQL_STATEMENT_WITH_DIAG_REC_OUTPUT宏。

该函数是用来通过MS SQL SERVER的BACKUP/DBCC命令获取动态的记录。函数内部实际是调用SQLGetDiagRec()函数。记录的索引从1开始计数。函数能自动的增加索引。更详细资料请见例：688、689

SQLHSTMT get_stm_handle()

仅ODBC适用

必须定义OTL_ODBC_SQL_STATEMENT_WITH_DIAG_REC_OUTPUT宏。

该函数用来返回底层的ODBC句柄。

int is_null()

测试是否stream返回一个空值

void set_lob_stream_mode(const bool mode = false)

设置log_stream_mode标识。该标识通知流使用otl_lob_stream操作。在OCI8上面该函数不是必须的，不过在ODBC/DB2 CLI或是otl_stream_read_iterator一起使用的时候，必须设置该值。或是在代码里面添加多数据库支持的时候，必须调用该函数。

long get_rpc()

返回数据库本次操作返回的记录行数。

返回的数据由INSERT/UPDATE/DELETE语句返回的操作行数；对于INSERT操作，它返回的是小于或等于缓冲区大小。对于UPDATE或DELETE语句，它取决于实际更新或删除的行数。

在4.0.6及以后的版本中，该函数对于SELECT语句返回的是累计操作的行数。

对于ORACLE和DB2 CLI或ODBC，该函数返回值有些不同。如对于出错状态的情况下，ORACLE返回的是实际成功的行数，而对于DB2或ODBC它返回的总是0.

结论：对于想兼容所有的数据库来说，该函数并不适用于所有的数据库。但对于ORACLE的不同版本的数据库来说，它还是通用的。

void set_commit(int auto_commit = 0)

设置流的auto-commit标识。

当流的输出缓冲区刷新的时候，就会自动进行事务提交操作。

如果想避免自动提交，请设置自动提交标识为false。

该自动提交标识与数据库的自动提交是两码事，该自动提交标识只是OTL自己的自动事务提交标识。

实际上设置为非自动提交还是非常方便的，在这种情况下，就可以使用otl_nocommit_stream类。otl_nocommit_stream类是一个直接继承otl_stream类的子类，仅是关闭了自动提交标识。

void set_flush(const bool auto_flush = true)

设置流的自动刷新标识。

默认值为真。实际上，流的析构函数试图进行刷新操作。自动刷新标识可以通过该函数进行关闭。如果自动刷新标识被关闭后，流就必须通过otl_stream::close()或otl_stream::flush()操作来强制刷新流，因为就算流的脏标志为真的情况下流的析构函数也不会去刷新缓冲区。

该函数仅是禁止析构函数里面的自动刷新功能。对于一般的缓冲区提交不能禁止。例如缓冲区满的情况下还是会自动进行刷新操作。

otl_var_desc * describe_out_vars(int & desc_len)

一组用来分析流的输入或输出绑定变量的函数。函数返回一个otl_var_desc结构体的指针。

otl_var_desc类类型如下：

序号	类型	说明
1	int param_type	0:输入变量 1:输出变量 2输入输出变量
2	int ftype	otl的数据类型，详细见OTL类型与数据库类型对比表
3	int elem_size	元素大小
4	int array_size	数组大小。对于标量来说，总是1
5	int pos	在SELECT语句里面，表示一个相对的输出变量的位置，如1、2、3
6	int name_pos	在定义了语句占位符的情况下，它表示占位符的相对的位置。如0,1,2
7	char name[128]	在变量定义为占位符的情况下，它表里前127个字节
8	int pl_tab_flag	在OCI里面，如果变量定义为表名，则值为1,否则为0

该函数用来取得输出变量的属性，参数desc_len返回的是otl_var_desc结构体大小。如果流里面没有输出参数，则返回0。如果有参数同时为输入和输出参数，它返回输出参数部分。

流的输出参数指的是取出流的部分。

otl_var_desc * describe_in_vars(int & desc_len)

该函数用来取得输入变量的属性，参数desc_len返回的是otl_var_desc结构体大小。如果流里面没有输入参数，则返回0。如果有参数同时为输入和输出参数，它返回输入参数部分。

流的输入参数指的是输入流的部分。

otl_var_desc * describe_next_out_var()

取得下一步输出变量。“下一个”指的是从流中读取了以后，下一个读出来的输出变量。比如调用了otl_stream::operator<<()后，有时候我们想要知道下一步输出变量的类型。如果没有下一个变量的时候，函数返回0.

otl_var_desc * describe_next_in_var()

取得下一步输入变量。“下一个”指的是从往流中写入了以后，下一个写入的输入变量。比如调用了otl_stream::operator<<()后，有时候我们想要知道下一步输入变量的类型。如果没有下一个变量的时候，函数返回0.

(1) void close()

关闭流。该函数与C++里面的流具有相同的概念。该函数有两个版本，一个是普通的版本，另一个是在定义了OTL_STREAM_POOLING_ON宏下的另一个版本。

(2) void close(const bool save_in_stream_pool = true)

定义了OTL_STREAM_POOLING_ON宏情况下使用。

save_in_stream_pool标志是一个初始化标志。当它设置为真的时候，在定义了OTL_STREAM_POOLING_ON宏的情况下，关闭一个流，并非真正的把流关闭了，而是把该流放到一个流缓冲池下面。如果后续还要接着使用该流，那直接调用缓冲池里面的流就可以，而不用重新再新建一个流。

如果标志设置为假，那么关闭流的时候就是真正关闭了流。

在对于某些流需要消耗大量系统资源的情况下，该参数非常有用。因为可以减少分配、删除流资源的时间而提高性能。

更详细的请见例：113、114、115

int good()

测试流是否是打开的。与C＋＋里面的流打开具有相同的功能。

otl_column_desc * describe_select(int & desc_len)

取得流的输出变量的字段列表。

仅对下列有效：

straight SELECT statement (OCIx, ODBC, and DB2-CLI)
Referenced cursor (OCIx)
Result set returned via a stored procedure call (ODBC for MS SQL Server and Sybase, DB2-CLI for DB2)

函数返回otl_column_desc结构体的指针。otl_column_desc类型如下：

序号	成员变量	说明
1	char * name	字段名
2	int dbtype	该值依赖于特定的数据库。对于OCI或ODBC有不同的值，详细请参见数据库。
3	int otl_var_dbtype	OTL定义的字段类型编码
4	int dbsize	字段长度
5	int scale	数值类型的精度
6	int prec	数值类型的小数位
7	int nullok	指定字段是否为空
8	int charset_form	仅在定义了OTL_UNICODE和OTL_ORA9I/OTL_ORA10G宏时候有效。 1：单字节 2：双字节 3：其他
9	int char_size	仅在定义了OTL_UNICODE和OTL_ORA9I/OTL_ORA10G宏时候有效。字段长度（按字母），在OTL_ORA8I情况下该值为0,因为相应的属性不被支持。

OTL定义了如下的类型与相应的数据库类型相对应：

序号	OTL类型常量	OTL类型编码	对应的数据库类型
1	otl_var_bigint	20	MS SQL SERVER/DB2/MYSQL/POSTGRESQL里面的bigint类型（singed 64 bit integer）
2	otl_var_blob	12	oracle8/9/10/11里面的blob类型
3	otl_var_char	1	NULL结尾的字符类型
4	otl_var_clob	11	oracle8/9/10/11里面的clob类型
5	otl_var_db2date	17	db2 date类型
6	otl_var_db2time	16	db2 time类型
7	otl_var_double	2	8字节长度的浮点型
8	otl_var_float	3	4字节长度的浮点型
9	otl_var_int	4	有符号的32位整形
10	otl_var_long_int	7	对于LLP64的C＋＋编译器是32位有符号整形；对于LP－64编译器，则是64位有符号整形
11	otl_var_ltz_timestamp	19	对于ORACLE 9I/10G/11G，带有TIME ZONE的TIMESTAMP类型
12	otl_var_raw	23	RAW, BINARY, VARBINARY, BYTEA, VARCHAR BYTE, CHAR BYTE类型
13	otl_var_raw_long	10	ORACLE里面的LONG RAW；MS SQL SERVER/SYBASE里面的IMAGE；DB2里面的BLOB类型
14	otl_var_short	6	16位有符号整型
15	otl_var_timestamp	8	ORACLE的TIMESTAMP; DB2的TIMESTAMP； MS SQL的DATETIME/DATETIME2/TIME/DATE; SYBASE的TIMESTAMP类型
16	otl_var_tz_timestamp	18	ORACLE下的带timezone的timestamp
17	otl_var_unsigned_int	5	无符号32位整型
18	otl_var_varchar_long	9	ORACLE里面的LONG； MS SQL里面的TEXT； DB2的CLOB类型

除了返回结构体的指针外，该函数还返回一个desc_len的参数。该参数表示返回的字段列表的长度。该函数返回的结构的指针不用用户删除，流里面在析构的时候会处理删除任务。

void reset_to_last_valid_row()

当OTL抛出“incompatible data type in stream operation”异常的时候，该异常为OTL内部的异常，它在流里面的SQL执行之前抛出，此时reset_to_last_valid_row()函数就能把输出缓冲区恢复到最后一个正确的位置。这个时候就能正确的调用flush()操作。如下：

   otl_stream str
   (100,
    "INSERT INTO test_tab VALUES(:f1<int>,:f2<char[31]>)",
   db);
   ...
   try{
     // writing rows into the stream
     ...
   }catch(const otl_exception& ex){
      if(ex.code==32000){
       str.reset_to_last_valid_row();
       str.flush();
      }
   }