OTL翻译(4) -- otl_stream类

序号

函数名

说明

1

otl_stream(…)

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

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

2

otl_stream(…)

仅ODBC/DB2 CLI

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

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

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

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

3

void open(…)

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

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

4

void open(…)

仅ODBC/DB2 CLI

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

5

int eof()

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

6

int setBufSize(const int buf_size)

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

7

void flush()

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

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

8

void flush(…)

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

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

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

9

int get_auto_commit_flag()

取得自动提交标识。

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

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

10

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

11

static void create_stored_proc_call(…)

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

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

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

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

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

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

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

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

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

12

void clean(const int clean_up_error_flag = 0)

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

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

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

13

void rewind()

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

14

operator int()

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

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

15

void cancal()

仅ODBC / DB2 CLI。

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

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

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

16

bool get_next_diag_rec(…)

仅支持ODBC。

必须定义OTL_ODBC_SQL_STATEMENT_WITH_DIAG_REC_OUTPUT宏。

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

17

SQLHSTMT get_stm_handle()

仅ODBC适用

必须定义OTL_ODBC_SQL_STATEMENT_WITH_DIAG_REC_OUTPUT宏。

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

18

int is_null()

测试是否stream返回一个空值

19

void set_lob_stream_mode(const bool mode = false)

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

20

long get_rpc()

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

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

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

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

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

21

void set_commit(int auto_commit = 0)

设置流的auto-commit标识。

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

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

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

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

22

void set_flush(const bool auto_flush = true)

设置流的自动刷新标识。

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

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

23

otl_var_desc * describe_out_vars(int & desc_len)

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

otl_var_desc类类型如下：

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

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

24

otl_var_desc * describe_in_vars(int & desc_len)

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

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

25

otl_var_desc * describe_next_out_var()

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

26

otl_var_desc * describe_next_in_var()

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

27

(1) void close()

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

28

(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

29

int good()

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

30

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类型如下：

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

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

31

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();
      }
   }

32

otl_stream & operator>>(unsigned char * s)

从流里面读取数据

当定义了OTL_UNICODE的时候，它返回的是以NULL结尾的双字节的字符串。否则返回的是单字节的字符串。