otl3_stream_class.htm

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

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//11 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
uses
Oracle system data dictionary directly (ALL_ARGUMENTS system view), in
order to retrieve information about stored procedure's parameters, and
their datatypes. Potentially, the function may raise the <a
 href="otl3_exc_list.htm">OTL
defined exceptions</a> with the following error codes: <a
 href="otl3_exc_list.htm#32014">32014</a>, <a
 href="otl3_exc_list.htm#32015">32015</a>, <a
 href="otl3_exc_list.htm#32016">32016</a>.</li>
&nbsp; <br>
  <p>The function is able to handle the following stored
procedures/functions: <br>
&nbsp; </p>
  <ul>
    <li>stored procedures / functions from PL/SQL packages only</li>
    <li>procedures / functions, whose names are not overloaded in the
package</li>
    <li>procedures / functions, with scalar input and/or output
parameters</li>
    <li>procedures / functions with scalar input parameters and one
output
reference
cursor:</li>
    <ul>
      <li>in the case of a procedure, the reference cursor should be an
OUT or
IN/OUT
parameter in the procedure</li>
      <li>in the case of a function, the reference cursor should be a
function
return
value.</li>
    </ul>
  </ul>
  <p><br>
  <tt>&nbsp;static void create_stored_proc_call</tt> <br>
  <tt>&nbsp;(otl_connect&amp; db, // connect object</tt> <br>
  <tt>&nbsp; otl_stream&amp; args_strm, // an instance of otl_stream
that is external to this</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // function. In other words,
an otl_stream variable that needs to</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // be defined externally.
The variable is used to instantiate the stream</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // with "SELECT...FROM
ALL_ARGUMENTS...",
in order for the function to</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // be able to access the
Oracle
system data dictionary. The stream gets</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // instantiated once, and
can be reused in subsequent calls to</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the function, especially,
in a high volume environment.</tt> <br>
  <tt>&nbsp; char* sql_stm, // output, otl_stream compatible SQL
statement,
which has</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// a call to the stored procedure, with all of the stored</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// proc's parameters expanded.</tt> <br>
  <tt>&nbsp; int&amp; stm_type, // output, stream/statement <a
 href="#stream_types">type</a></tt> <br>
  <tt>&nbsp; char* refcur_placeholder, // output, in case of a stored
procedure, returnig a</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // a reference cursor, this
parameter returns a "reference cursor</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // placeholder" name, that
can be used in <a href="#otl_stream_otl_stream">otl_stream::otl_stream</a>(),
or</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // in <a
 href="#otl_stream_open">otl_stream::open</a>()
calls.</tt> <br>
  <tt>&nbsp; const char* proc_name, // stored procedure name. this
should
a stored</tt> <br>
  <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// procedure from a PL/SQL package</tt> <br>
  <tt>&nbsp; const char* package_name, // PL/SQL package name, which
the stored procedure</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;
// belongs to</tt> <br>
  <tt>&nbsp; const char* schema_name=0, // Oracle schema name, which
the stored procedure</tt> <br>
  <tt>&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;&nbsp;&nbsp;
// and/or the PL/SQL package belong to</tt> <br>
  <tt>&nbsp; const bool schema_name_included=false, // indicator of
whether
the call to</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// the stored procedure needs to be</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// prefixed with the schema name or not</tt> <br>
  <tt>&nbsp; const int varchar_size=2001, // VARCHAR parameters in
stored
procedure</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;
// don't have any sizes. This parameter defines</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;
// what size needs to be used in the definitions</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;
// of :var&lt;char[XXX] bind variables.</tt> <br>
  <tt>&nbsp; const int all_num2type=<a href="#otl_var_double">otl_var_double</a>
// This parameter defines how NUMBER</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// parameters of the stored procedure</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// will mapped to the corresponding</tt> <br>
  <tt>&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// bind variable definitions.</tt> <br>
  <tt>);</tt> <br>
&nbsp;</p>
</ul>
<ul>
  <li>Clean up the stream output buffer without <a href="#flush">flushing</a>
it. The <i>clean_up_error_flag </i>parameter, if set to 1, cleans up
the
otl_stream's internal error flag that usually gets set when the stream
throws an <a href="otl3_exception_class.htm">otl_exception</a>.See
examples <a href="otl3_ex65.htm">65</a>, <a href="otl3_ex66.htm">66</a>,
    <a href="otl3_ex67.htm">67</a>
for more detail on this parameter. The main purpose for introducing
this
parameter was to provide the stream a capability to recover from
adatabase
error without closing out the stream.</li>
  <p>In OTL 4.0.6, and later, the function is extended to work with
SELECT
statements, explicit (Oracle reference cursors) and implicit (in DB2,
MS
SQL Server, or Sybase stored procedures) result sets. An unfinished
fetch
sequence can be canceled by calling the function. Also, the function
cleans
up the error flags, that get set inside the stream, in the case of,
say,
a database error.</p>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="clean"></a>void clean(const int clean_up_error_flag=0);</pre>
<ul>
  <li>Rewind the stream. If the stream does not have any input
variables,
this
function forces the stream to execute its SQL statement.</li>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp; void rewind(void);</pre>
<ul>
  <li>OTL-stream-to-int conversion operator It returns the !eof()
status of
the
stream. It allows the operators <a href="operator_gg">&gt;&gt;</a> to
return
the !EOF status of the stream, and to be used in a while() loop as
follows:</li>
</ul>
<tt><font size="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
while(s&gt;&gt;f1&gt;&gt;f2){</font></tt>
<br>
<tt><font size="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
cout&lt;&lt;"f1="&lt;&lt;f1&lt;&lt;", f2="&lt;&lt;f2&lt;&lt;endl;</font></tt>
<br>
<tt><font size="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</font></tt>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="operator_int"></a>operator int(void);</pre>
<ul>
  <li>OTL/ODBC, OTL/DB2-CLI only. If the stream has a running SELECT
statement,
or a call to a stored procedure that returns a result set, in one
worker
thread (not the main thread), then the statement can be asynchronously
canceled, by calling this function from another worker thread. The
actual
cancellation of the statement depends on how the SQLCancel() call
(ODBC,
or DB2-CLI) was implemented in the underlying database API. Also, the
error
code, that otl_exception gets initialized with, depends on the
underlying
database API. In some cases, the error code is 0, but an otl_exception
gets thrown, right after the SQLCancel call returns.</li>
  <p>OTL/OCI8,8i,9i,10g have a similar function but at the level of
otl_connect: <a href="otl3_connect_class.htm#cancel">cancel</a>(). OCI
and
ODBC/DB2-CLI
are different in that regard.</p>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="cancel"></a>void cancel(void);</pre>
<ul>
  <li>Test if NULL was fetched from the stream</li>
</ul>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a name="is_null"></a>int is_null(void);</pre>
<ul>
  <li>Set the <a href="otl3_lob_stream.htm">LOB stream mode</a>. This
function