📄 otl3_stream_class.htm
字号:
<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author" content="Sergei Kuchin">
<meta name="GENERATOR"
content="Mozilla/4.78 [en] (Windows NT 5.0; U) [Netscape]">
<meta name="KeyWords"
content="OTL, Oracle, ODBC, DB2, CLI, database API, C++, Template Library">
<title>OTL 4.0, OTL stream class</title>
</head>
<body>
<center>
<h1>OTL 4.0, OTL stream class</h1>
</center>
<h1>
<a name="otl_stream_class"></a>OTL stream class</h1>
The otl_strean class is the actual implemention the <a
href="otl3_str.htm">OTL
stream concept</a>. Any SQL statement, anonymous PL/SQL block or stored
procedure with input and/or output parameters can be programmed in C++
with the otl_stream class.
<p>Traditionally, a database API has functions to bind host variables
with
placeholders in the SQL statement. So, the developer has to declare
host
arrays in the program, parse the statement, call the bind functions,
fill
out the input variables, execute the statement, read the output
variables,
etc. After the cycle is done, again, fill out the input variables,
execute
the statement, read the output. All that is done automatically in the
otl_stream
class. The class provides full automation of interaction with the
database
as well as performance. Performance is controlled by a single parameter
-- the stream <a name="buffer_size"></a><i>buffer size. </i>The
buffer size is defined in logical rows to inserted into a table,
selected from a table / view in one round-trip to the database (a.k.a.
batch size, array size).<br>
</p>
<p>A SQL statement in the otl_stream needs to have at least one <a
href="otl3_bind_variables.htm">placeholder
/ bind variable</a>. SQL statements without placeholders are referred
to
as <a href="otl3_const_sql.htm">constant SQL statements.</a> and
processed
differently.<br>
</p>
<p>Starting with OTL 4.0.115 and on, the buffer size datatype is <span
style="font-style: italic;">int </span>(the old datatype was <span
style="font-style: italic;">short int</span>). If the old datatype is
needed for backward compatibility, #define <a
href="otl3_compile.htm#OTL_STREAM_LEGACY_BUFFER_SIZE_TYPE">OTL_STREAM_LEGACY_BUFFER_SIZE_TYPE</a>
has to be enabled.<br>
</p>
<p>
</p>
<p>The otl_stream class has the following structure:
</p>
<pre><font size="+2">class otl_stream {<br>public:</font></pre>
<ul>
<li>General constructor. This constructor creates an otl_stream
object and
then calls the <a href="#open">open()</a> function. There two flavors
of
the otl_streams:</li>
<br>
<b>for Oracle 7/8/9/10:</b>
</ul>
<pre> <a name="otl_stream_otl_stream"></a>otl_stream(const int arr_size, // stream <a
href="#buffer_size">buffer size<br></a> const char* sqlstm, // SQL statement or anynonymous PL/SQL block<br> <a
href="otl3_connect_class.htm">otl_connect</a>& db, // OTL connect object<br> <a
name="ref_cur"></a>const char* ref_cur_placeholder=0,<br> // If the stream returns a referenced cursor,<br> // this parameter is used to specify the name of the <br> // referenced cursor placeholder.<br> const char* sqlstm_label=0<br> // SQL statement label. When specified, it is used<br> // to populate <a
href="otl3_exception_class.htm#stm_text">otl_exception::stm_text</a> with, so<br> // the actual text of the SQL statement will not be visible<br> // and will be replaced with its label.<br> );</pre>
<ul>
<b>for ODBC/DB2-CLI:</b>
<pre>otl_stream(const int arr_size, // stream <a href="#buffer_size">buffer size<br></a> const char* sqlstm, // SQL statement or stored procedure call<br> <a
href="otl3_connect_class.htm">otl_connect</a>& db, // connect object<br> const int implicit_select=otl_explicit_select,<br> // If the stream returns a result set via a strored <br> // procedure call, this parameter needs to be set to <br> // otl_implicit_select<br> const char* sqlstm_label=0<br> // SQL statement label. When specified, it is used<br> // to populate <a
href="otl3_exception_class.htm#stm_text">otl_exception::stm_text</a> with, so<br> // the actual text of the SQL statement will not be visible<br> // and will be replaced with its label.<br> );</pre>
<a name="implicit_select"></a><font size="-1">OTL 4.0/ODBC and OTL
4.0/DB2-CLI
define the following global constant to be used with this constructor:</font>
<ul>
<li> <font size="-1"><b>otl_explicit_select</b> -- to indicate
that if
the stream
is a SELECT statement then the statement is a simple SELECT.</font></li>
<li> <font size="-1"><b>otl_implicit_select</b> -- to indicate
that
the stream
is a stored procedure call that returns a result set.</font></li>
</ul>
</ul>
<ul>
<a name="open"></a>This function opens the SQL statement: the
statement
gets parsed, all input and output <a href="otl3_bind_variables.htm">variables</a>
get dynamically allocated inside the stream and automatically bound to
the placeholders. There are two flavors of the function: <br>
<p><b>For Oracle 7/8/9/10:</b></p>
</ul>
<pre> <a name="otl_stream_open"></a>void open(const int arr_size, // stream <a
href="#buffer_size">buffer size<br></a> const char* sqlstm, // SQL statemnet or anynonymous PL/SQL block<br> <a
href="otl3_connect_class.htm">otl_connect</a>& db, // connect object<br> const char* ref_cur_placeholder=0,<br> // If the stream returns a referenced cursor,<br> // this parameter is used to specify the name of the <br> // referenced cursor placeholder.<br> const char* sqlstm_label=0<br> // SQL statement label. When specified, it is used<br> // to populate <a
href="otl3_exception_class.htm#stm_text">otl_exception::stm_text</a> with, so<br> // the actual text of the SQL statement will not be visible<br> // and will be replaced with its label.<br> );</pre>
<ul>
<pre><b>For ODBC/DB2-CLI:</b></pre>
</ul>
<pre> void open(const int arr_size, // stream <a
href="#buffer_size">buffer size<br></a> const char* sqlstm, // SQL statemnet or stored procedure call<br> <a
href="otl3_connect_class.htm">otl_connect</a>& db, // connect object<br> const int implicit_select=otl_explicit_select,<br> // If the stream returns a result set via a strored <br> // procedure call, this parameter needs to be set to <br> // otl_implicit_select<br> const char* sqlstm_label=0<br> // SQL statement label. When specified, it is used<br> // to populate <a
href="otl3_exception_class.htm#stm_text">otl_exception::stm_text</a> with, so<br> // the actual text of the SQL statement will not be visible<br> // and will be replaced with its label.<br> );</pre>
<ul>
<li><a name="eof"></a>Test if all data has been already read from the
stream. This
function
has
the same meaning as the eof() funtion in C++ streams</li>
</ul>
<pre> int eof(void);<br><br></pre>
<ul>
<li><a name="setBufSize"></a>Set the stream buffer size. The only
thing that this function does is saves a new buffer size for further
use with otl_connect::operator<a
href="otl3_connect_class.htm#operator_gg">>></a>(otl_stream&).<br>
</li>
</ul>
<pre> int setBufSize(const int buf_size);</pre>
<ul>
<li> <a name="flush"></a>Flush the stream output buffer. It actually
means to
execute the SQL statement in <a href="otl3_str.htm#bulk">bulk</a> as
many
times as rows entered into the stream output buffer. The stream is
automatically
flushed when the buffer gets full. This function has the same meaning
as
the flush() function in C++ streams. Also, if the stream <tt><i>auto-commi</i>t</tt>
flag is set then the stream, after flushing the output buffer, commits
the current transaction. For more detail, see the <a href="#set_commit">set_commit</a>()
function.</li>
<br>
<p>OTL/OCI8,8i,9i/10g has a version of the flush function with 2
parameters:
row_offset, force_flushing This version of the flush function makes the
process of, say, inserting a big batch of rows more efficient, after,
say,
duplicate rows were discovered in the batch, and an otl_exception was
raised.
For more detail, see OTL examples.</p>
</ul>
<pre> void flush(void);<br><br> void flush // OTL/OCI8,8i,9i,10g only <br> (const int row_offset=0, // Specify the first row in the<br> // stream's buffer for flushing<br> const bool force_flush=false // Force flushing regardless of <br> // previous errors<br> );</pre>
<ul>
<li> <a name="get_stream_type"></a>OTL/OCI8/9/10 only. Get the OTL
stream
type.</li>
<p><tt> int get_stream_type(void);</tt> </p>
<p>The following global constants (int's) are defined: <br>
</p>
<ul>
<li> <a name="stream_types"></a><b><font size="-1">otl_no_stream_type</font></b>
-- stream is not instantiated with any SQL statement yet.</li>
<li> <b><font size="-1">otl_select_stream_type</font></b> --
stream is
instantiated
with a straight SELECT statement.</li>
<li> <b><font size="-1">otl_inout_stream_type</font></b> -- stream
is
instantiated
with an anonymous PL/SQL block which has input/output bind variables,
possibly,
parameters in a stored procedure call.</li>
<li> <b><font size="-1">otl_refcur_stream_type</font></b> --
stream is
instantiated
with a PL/SQL block, which returns a reference cursor. In this type of
a PL/SQL block (possibly, a stored procedure call), only input bind
variables
are allowed. The output of the PL/SQL block is the reference cursor
itself.</li>
<li> <b><font size="-1">otl_constant_sql_type</font></b> --
special
constant that
is only used in <tt><a href="#create_stored_proc_call">create_stored_proc_call()</a></tt>,
and not returned by <a href="#get_stream_type">get_stream_type</a>().
However,
the constant completes this logical group of constants, that represent
types of OTL streams. In the context of
create_stored_proc_call(),
this constant indicates a call to a stored procedure, which has no
parameters,
and it needs to be executed via <a href="otl3_const_sql.htm">otl_cursor::direct_exec</a>().</li>
</ul>
</ul>
<ul>
<li> <a name="create_stored_proc_call"></a>OTL/OCI8/9/10 only.
Create
an
otl_stream
compatible call (string) to a stored procedure by the stored procedure
name. This function is static in class and intended for some automation
in generating Oracle 8/8i/9i/10g stored procedure calls. The function
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -