otl3_stream_class.htm

ISO_C++:C++_OTL开发文档

sets the "lob stream mode" flag in the otl_stream, that is, this tells
the otl_stream that <a href="otl3_lob_stream.htm">otl_lob_stream</a>
operations
will be used. It is not required that this function be used in case of
OTL/OCI8. For OTL/ODBC and OTL/DB2-CLI, or when the <a
 href="otl4_stream_read_iterator.htm">otl_stream_read_iterator</a> is
used, it is required. However, for
writing
portable [across multiple database] code, the function should be called.</li>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="set_lob_stream_mode"></a>void set_lob_stream_mode(const bool mode=false);</pre>
<ul>
  <li>Get the <i>ROWS PROCESSED COUNT </i>(RPC). The count is defined
for
INSERT,
UPDATE, DELETE statements, and it shows how rows have been processed in
the last execution of the statement. For INSERT statements, it may be
less
or equal to the stream <a href="#buffer_size">buffer size</a>.For
DELETE
or UPDATE statements, it may be anything, depending upon what how may
rows
are being updated or deleted.</li>
  <p>In OTL 4.0.6 and higher, the function was extended to return an
accumulative
rows processed count for SELECT statements (all databases), reference
cursors
(Oracle), stored procedures that return implicit result sets.</p>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="get_rpc"></a>long get_rpc(void);</pre>
<blockquote>There is a substantial difference in the way the get_rpc()
function works in Oracle and ODBC, or DB2-CLI, in the case of an error,
when the underlying INSERT/UPDATE/DELETE statement errored out with an
otl_exception. In Oracle, in case of error, get_rpc() returns a number
of successfully processed rows, so it's easy to calculate which row
caused
the error. In ODBC, or DB2-CLI, the behavior of the SQLGetRowCount()
function
is undefined, so get_rpc() always returns 0.
  <p><i>Conclusion: </i>for portable, muti-database OTL based code,
it's
not recommended to use the database specific behavior of the get_rpc()
function. For Oracle OTL based code, it's okay to use it, since this
kind
of behavior is consistent with all versions of Oracle, that are
supported
by OTL.</p>
</blockquote>
<ul>
  <li> <a name="set_commit"></a>Set the stream <i>auto-commit</i>
flag.
When the
output buffer is <a href="#flush">flushed</a>, the current transaction
is automatically commited, if the flag is set. By default, the flag is
set. In order to prevent the current transaction from
"auto-committing",
unset the flag using this function. The stream auto-commit flag has
nothing
to do with the database auto-commit mode. The auto-commit is specific
to
the otl_stream class.</li>
  <p><a name="nocommit"></a>If it is more convenient to have the stream
"auto-commit
off" by default, then the <font size="+1">otl_nocommit_stream </font>can
be used. otl_nocommit_stream is a class derived directly from
otl_stream
with <i>auto-commit</i> turned off by default, so it does not commit
transactions. </p>
  <pre>&nbsp;&nbsp;&nbsp;&nbsp; void set_commit(int auto_commit=0);</pre>
</ul>
<ul>
  <li> <a name="set_flush"></a>Set the stream's <i>auto-flush</i>
flag.
Default
value is <i>true</i>. By default, the stream's destructor tries to
flush
the buffer, if the buffer is <i>dirty</i>. It is called <i>auto-flushing</i>.
The auto-flushing can be turned off or on explicitly with the help of
the
set_flush() function (see below). If the auto-flush flag was turned
off,
the stream's buffer needs to be flushed either by calling the
otl_stream::close()
function or the otl_stream::flush() function, because the destructor
would
not flush even if the <i>dirty </i>flag is true. This function could
be
especially useful, when OTL is used in the environment with exceptions
get thrown left and right, to prevent the otl_stream's destructor from
auto-flushing the buffer in the stack unwinding.</li>
  <p>This function disables ONLY auto-flushing in the otl_stream
destructor,
not the buffer flushing in general. When the stream buffer gets full,
it
gets flushed automatically REGARDLESS. If set_flush(false) call was
made,
it disables the automatic buffer flushing ONLY in the DESTRUCTOR, in
order
to prevent potential cascading otl_exception's.</p>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp; void set_flush(const bool auto_flush=true);</pre>
<ul>
  <li> <a name="describe_vars"></a>A group of functions for describing
otl_stream's
bind variables, both <i>input</i> and <i>output</i>. The functions
return
a pointer to the otl_var_desc structure:</li>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="otl_var_desc"></a>class otl_var_desc{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; public:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; param_type; // 0 - IN variable, 1 - OUT variable, 2 - INOUT variable<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; ftype; // see the <a
 href="#otl_var_dbtype">OTL codes for mapped datatypes<br></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; elem_size; // [array] element size in bytes.<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; array_size; // array size, in case if the variable is scalar, the size<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // is equal to 1<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; pos;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // In SELECT statements, pos shows a relative position<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // of the output column: 1,2,3,...<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; name_pos;&nbsp;&nbsp; // In case if the variable is defined via the placeholder<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // notation (:var&lt;...&gt;), name_pos shows a relative position<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // of the variable in the arrays of varaibles: 0,1,2,...<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char name[128]; // First 127 bytes of the variable name, in case if the&nbsp;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // variable was defined as a placeholder.<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int&nbsp; pl_tab_flag; // In OTL/OCIx, this field is equal to 1 in case if the&nbsp;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // variable is defined as a PL/SQL table, 0 - otherwise.<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; };</pre>
<ul>
  <ul>
    <li>&nbsp;Describe OUT variables. <i>desc_len</i> returns the size
of the
array
of otl_var_desc structures. The function returns a pointer to the array
of OUT variable descriptors. In case if the SQL statement does not
contain
any output variables, the functions returns 0. If a variable was
declared
as INOUT, it is presented as part of the array of the variable
descriptors,
returned by this function.</li>
    <p>OUT variables are the variables that get read FROM the stream.</p>
  </ul>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
 name="describe_out_vars"></a><a href="#otl_var_desc">otl_var_desc</a>* describe_out_vars(int&amp; desc_len);</pre>
<ul>
  <ul>
    <li>&nbsp;Describe IN variables. <i>desc_len</i> returns the size
of the
array
of otl_var_desc structures. The function returns a pointer to the array
of IN variable descriptors. In case if the SQL statement does not
contain
any input variables, the functions returns 0. If a variable was
declared
as INOUT, it is presented as part of the array of the variable
descriptors,
returned by this function.</li>
    <br>
IN variables are the variables that get written TO the stream.
  </ul>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
 name="describe_in_vars"></a><a href="#otl_var_desc">otl_var_desc</a>* describe_in_vars(int&amp; desc_len);</pre>
<ul>
  <ul>
    <li>&nbsp;Describe <i>next</i> output variable. Next means "next
to be
read
from the stream." That is, before calling one of
otl_stream::operator&lt;&lt;(),
sometimes it is necessary to know what is the type of the next variable
to be read. In case if the stream does not have any output variables,
the
function returns 0.</li>
  </ul>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
 name="describe_next_out_var"></a><a href="#otl_var_desc">otl_var_desc</a>* describe_next_out_var(void);</pre>
<ul>
  <ul>
    <li>&nbsp;Describe <i>next</i> input variable. Next means "next to
be
written
to the stream." That is, before calling one of
otl_stream::operator&gt;&gt;(),
sometimes it is necessary to know what is the type of the next variable
to be written. In case if the stream does not have any input variables,
the function returns 0.</li>
  </ul>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
 name="describe_next_in_var"></a><a href="#otl_var_desc">otl_var_desc</a>* describe_next_in_var(void);</pre>
<ul>
  <li> <a name="close"></a>Close the stream. This function has the
same
meaning
as the close() function in C++ streams. The close() function has two
implemenations:
the ordinary one <i>(1)</i>, and the extended one <i>(2)</i>, under
#define <a href="otl3_compile.htm#OTL_STREAM_POOLING_ON">OTL_STREAM_POOLING_ON</a>.</li>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp; <i>(1)</i> void close(void);</pre>
<ul>
  <i>save_in_<a href="otl3_stream_pooling.htm">stream_pool</a></i> is
an initialized parameter in the function. When it's set to <i>true</i>,
and if #define OTL_STREAM_POOLING_ON is on, the stream doesn't really
get
closed. The stream gets saved to the pool of unused OTL streams, which
can be reused later, when a similar stream (SQL statement + buffer
size)
gets opened again. The maximum size of the OTL stream pool can be set
by
otl_connect::<a href="otl3_connect_class.htm#set_stream_pool_size">set_stream_pool_size</a>().
  <p>When the save_in_stream_pool parameter is set to <i>false</i>,
the stream
DOES get closed, and doesn't get saved in any stream pool. This setting
of the parameter can be used to override the default behavior of the
otl_stream
under #define OTL_STREAM_POOLING_ON. For example, a stream with huge
SQL