📄 otl3_connect_class.htm
字号:
const OTL_UNICODE_CHAR_TYPE* passwd, // password<br>
const OTL_UNICODE_CHAR_TYPE* dsn, // data source name<br>
const int auto_commit=0 // connect
auto-commit mode<br>
);<br>
<br>
#endif<br>
</span><tt><br>
</tt>
<ul>
<li><a name="ext_otl_connect_odbc"></a>General constructor: connect
to
the
primary database connection, which was made in straight ODBC, DB2-CLI,
or any other third-party (ODBC, or DB2-CLI based) library. This
function
works for <b><i>OTL/ODBC, DB2-CLI</i></b> only, and it helps to make
transition
from the legacy environment to the OTL environment smoother.</li>
</ul>
<pre> otl_connect(HENV henv, // environment handle<br> HDBC hdbc, // database connect handle<br> const int auto_commit=0 // connect auto-commit mode<br> );</pre>
<ul>
<li> <a name="attach8"></a>Log on / connect to / attach to the
primary
database
connection, which was made in Pro*C/C++ or any other third-party
library.
This function works for <b><i>OTL/OCI8/8i/9i</i></b> only, and it
helps
to make integration of OTL/OCI8/8i/9i and the Pro*C/C++ environment
smooth
and easy. In order to use this function in the Pro*C/C++ environment,
#define
OTL_ORA8_PROC needs to be set at the beginning of the program. For more
detail, see example <a href="otl3_ex59.htm">59</a></li>
<p><i>envhp</i> is a pointer to the OCI8/8i/9i environment handle,
which
needs to be obtained by calling the <i>SQLEnvGet</i> function. <br>
<i>svchp </i>is a pointer to the OCI8/8i/9i service context handle,
which needs to be obtained by calling the <i>SQLSvcCtxGet</i> function.</p>
</ul>
<pre> void rlogon(OCIEnv* envhp, OCISvcCtx* svchp);<br><br></pre>
<ul>
<li><a name="rlogon_xa"></a><b><i>OTL/OCI8/8i/9i/10g, </i></b>connect
to the database and set the following connection attributes that are
required by the Oracle XA Library: server external name, server
internal name. <br>
<br>
<pre> void rlogon(const char* connect_str,<br> const int aauto_commit=0,<br> const char* xa_server_external_name=0,<br> const char* xa_server_internal_name=0,<br>#if defined(<a
href="otl3_compile.htm#OTL_ORA_OCI_ENV_CREATE">OTL_ORA_OCI_ENV_CREATE</a>)<br> bool threaded_mode=false<br>#endif<br> );<br></pre>
</li>
</ul>
<ul>
<li> <a name="logoff"></a>Logs off / disconnects from the database.
In
case
if the primary connection was done in Pro*C/C++ (OTL/OCIx), this
function
just detaches from that connection without actually disconnecting from
the database.</li>
</ul>
<pre> void logoff(void);</pre>
<ul>
<li> <a name="attach_detach"></a>Attach to / detach from Oracle (<b><i>OTL/OCI8/8i/9i</i></b>
only). These functions are wrappers around the ServerAttach and
ServerDetach
functions of the OCI8. The main reason to have separate functions to
attach
to the server and then begin a session is performance. For more detail,
see Oracle's regular manuals. These functions, along with the <a
href="#session_begin">session_begin</a>
and <a href="#session_end">session_end</a> functions, could be used
for
implementing a connection management mechanism that is more efficient
than
the traditional connection pooling. See also example <a
href="otl3_ex60.htm">60</a>.<br>
</li>
</ul>
<pre> <a name="server_attach"></a>void server_attach(const char* tnsname=0, <br> const char* xa_server_external_name=0,<br> const char* xa_server_internal_name=0,<br>#if defined(<a
href="otl3_compile.htm#OTL_ORA_OCI_ENV_CREATE">OTL_ORA_OCI_ENV_CREATE</a>)<br> bool threaded_mode=false<br>#endif<br> )<br> // tnsname (TNS alias from TNSNAMES.ORA file) can be specified <br> // in order to connect to a remote Oracle 8 server. <br> // For local connections, tnsname defaults to 0.<br> // The function attaches to the database server (local or remote).<br> // The following "server attachment" attributes that are <br> // required by the Oracle XA Library can be also specified:<br> // server external name, server internal name. Also see <a
href="#rlogon_xa">rlogon</a>().<br><br><br> <a
name="server_detach"></a>void server_detach(void); // detach from the Oracle 8 server</pre>
<ul>
<li>Begin / end Oracle 8 session (<b><i>OTL/OCI8/8i/9i</i></b> only).
These
functions complement the server <a href="#attach_detach">attach/detach</a>
suite of functions, and are used to begin / end an Oracle 8 session.
The
main reason to have separate server attach/detach and session begin/end
groups of function is performance. session_begin() is approximately
50-100
times faster than the normal <a href="#rlogon">rlogon</a>(). These
functions,
along with the <a href="#attach_detach">server_attach</a>() and <a
href="#server_detach">server_detach</a>()
functions, could be used for implementing a connection management
mechanism
that is several times more efficient [thus, more scalable] than the
traditional
connection pooling.</li>
</ul>
<pre> <a name="session_begin"></a>void session_begin<br> (const char* username, // user name, e.g. "scott"<br> const char* password, // password, e.g. "tiger"<br> const int auto_commit=0, // session <a
href="#auto_commit">auto-commit</a> mode<br> const int session_mode=OCI_DEFAULT<br> // OCI_SYSDBA -- in this mode, the user is authenticated for SYSDBA<br> // access. <br> // OCI_SYSOPER -- in this mode, the user is authenticated<br> // for SYSOPER access.<br> );<br><br> <a
name="session_end"></a>void session_end(void);</pre>
<ul>
<li>Session reopen (<b><i>OTL/OCI8/8i/9i</i></b> only). If a session
was
started
via <a href="#session_begin">session_begin</a>() for a given <i>username/password</i>
and then closed via <a href="#session_end">session_end</a>(), another
session
can be started faster (5-10%) for the same username/password via
session_reopen().
This function takes advantage of the fact that the username and
password
attributes of the OCI8 internal connect structure have been already set
by the previous session_begin() function call. If a session has been
started
via session_reopen(), it can be closed by calling session_end(). </li>
<p>Also, see example <a href="otl3_ex61.htm">61</a></p>
</ul>
<pre> <a name="session_reopen"></a>void session_reopen(const int aauto_commit=0 // session <a
href="#auto_commit">auto-commit</a> mode<br> );</pre>
<ul>
<li>Commit transaction. In the otl_connect object, Oracle, ODBC and
DB2-CLI
connections, by default, are set to <i>auto-commit off. </i>This
means
that all transactions need to be commited by explicitly calling the
commit()
function. It is not recommended to use connections that are set to <i>auto-commit
on.</i></li>
<pre> <a name="commit"></a>void commit(void);<br><br></pre>
</ul>
<ul>
<li>Commit transaction asynchronously, same as commit and forget /
commit with no wait. At the moment, avalaible only for Oracle 10g
Release 2 (Oracle 10.2). As soon as the rest of the database vendors
release a similar feature, it will be implemented in OTL.<br>
</li>
</ul>
<ul>
<pre>#if defined(<a href="otl3_compile.htm#OTL_ORA10G_R2">OTL_ORA10G_R2</a>)<br> <a
name="commit_nowait"></a>void commit_nowait(void);<br>#endif<br></pre>
</ul>
<ul>
<li>Roll back transaction</li>
<pre> void rollback(void);</pre>
<li>Set otl_connect's <a href="#auto_commit">auto-commit</a> OFF and
ON,
within
one open session/connect. These two functions are for partial backward
compatibility only.</li>
<pre> <a name="auto_commit_off"></a>void auto_commit_off(void);<br> <a
name="auto_commit_on"></a>void auto_commit_on(void);</pre>
<li> <a name="set_stream_pool_size"></a>Set the <a
href="otl3_stream_pooling.htm">otl_stream
pool</a> size. This function can be activated with #define <a
href="otl3_compile.htm#OTL_STREAM_POOLING_ON">OTL_STREAM_POOLING_ON,</a>
used together with #define <a href="otl3_compile.htm#OTL_STL">OTL_STL</a>.
If OTL_STREAM_POOLING_ON is defined in the program, the function body
gets
included into the target code. Also, a default stream pool gets
allocated
as part the otl_connect object, even if the function doesn't get
called.
Therefore, a call to the function will reallocate all the resources,
allocated
by the default stream pool, or by previous calls to
set_stream_pool_size().</li>
</ul>
<pre> void set_stream_pool_size<br> (const int max_size=otl_max_default_pool_size);</pre>
<ul>
<li> <a name="set_character_set"></a>This function is available for
OTL/<b><i>OCI8i/9i</i><span style="font-style: italic;">/10g</span></b>
under #define <a href="otl3_compile.htm#OTL_UNICODE">OTL_UNICODE</a>
only.
In Unicode OTL, the Oracle database default or national character set
is
allowed to be set:</li>
<br>
<ul>
<li>SQLCS_IMPLICIT -- database default (implicit) character set</li>
<li>SQLCS_NCHAR -- database national (second) character set. </li>
<p><tt>void set_character_set(const int char_set=SQLCS_IMPLICIT);</tt></p>
</ul>
<p><br>
The default character set (SQLCS_IMPLICIT) needs to be set when
Unicode containers are used with the VARCHAR2, CHAR, LONG, and CLOB
column
types. In the case if Unicode containers are used with NVARCHAR2,
NCAHR,
and NCLOB datatypes, the national character set (SQLCS_NCHAR) needs to
be set. </p>
<p>SQLCS_IMPLICIT, and SQLCS_NCHAR are defined by the OCI header
files. </p>
<p>Since this function is part of the otl_connect class, all
otl_streams,
that gets opened via a concrete connect object, will use the character
set, that was set by the function. </p>
<p>The semantic of :var<<a href="otl3_bind_variables.htm#char">char</a>[...]...>
declaration of string bind variables was extended to accomodate the
Unicode
strings. For example, char[20] means a string of 19 double-byte Unicode
characters, plus 19 double-byte possible surrogate characters, plus one
double-byte null terminator. It sounds a little complicated, but that
is
just a reflection of a plethora of Unicode standards, coding
techniques.
It is strongly recommended to read the Unicode standards themselves,
then
the Oracle implementations the Unicode. By the way, Oracle 8i and 9i
differ
in that regard substantially.<br>
<br>
</p>
</ul>
<ul>
<li><a name="set_throw_on_sql_success_with_info"></a>OTL/ODBC,
OTL/DB2-CLI only. Set the "OTL throws on SQL_SUCCESS_WITH_INFO"" flag.
When the flag is set, and SQLExecDirect() / SQLExecute() function
returns SQL_SUCCESS_WITH_INFO, OTL throws an otl_exception. This is
useful for communicating more information from the SQL call, especially
if the call is a call to a stored procedure, or a Transact-SQL batch
that may return more diagnostic information than usual. The function is
enabled only when #define OTL_THROWS_ON_SQL_SUCCES_WITH_INFO is defined.<br>
</li>
<pre>#if defined(<a
href="otl3_compile.htm#OTL_THROWS_ON_SQL_SUCCESS_WITH_INFO">OTL_THROWS_ON_SQL_SUCCESS_WITH_INFO</a>)<br> void set_throw_on_sql_success_with_info(const bool throw_flag=false);<br>#endif<br><br></pre>
<li><a name="operator_ll"></a>Send a string to the otl_connect
object. If the object is not connected to a database then the string is
a connection
string in the "userid/passwd@db" format and it makes the object connect
to the database. If the object is already connected, the string is a
static SQL statement that the connect object executes immediately.<br>
<br>
<tt>otl_connect& operator<<(const char* str);<br>
<br>
<br>
</tt></li>
<li><a name="operator_lle"></a>Send a string to the otl_connect
object. The connect object saves the string for further use with
operator <a href="#operator_gg">>></a>(). The string is an SQL
statement with placeholders that could be sent to an otl_stream object.
In other words, this operator is a deferred SQL statement. <br>
<br>
<tt>otl_connect& operator<<=(const char* str);<br>
<br>
</tt></li>
<li><a name="operator_gg"></a>Send the SQL statement that was saved
with operator <a href="operator_lle"><<=</a> to an otl_stream
object. It makes the otl_stream object open the SQL statement. If there
was no SQL statement previously save by the connect object, the connect
object sends the following string to the otl_stream: <span
style="font-family: monospace;">"*** INVALID COMMAND ***"</span>.,
which causes an SQL parse error in the otl_stream, which ends up in an
otl_exception.<br>
<br>
<tt>otl_connect& operator>>(otl_stream& s);<br>
<br>
</tt></li>
<li><a name="direct_exec"></a>Direct execution of a static SQL
statement, the function returns the
Rows Processed Count (RPC)<br>
<br>
<tt>long direct_exec(const char *sqlstm, // SQL Statement<br>
int ignore_error =</tt><tt> </tt><a
href="otl3_exception_class.htm#enum"><span
style="font-family: monospace;">otl_exception::enabled</span></a><tt>
// "ignore error" flag </tt><br>
<tt>
);<br>
<br>
</tt></li>
<li><a name="syntax_check"></a>Parses a static SQL statement,
raises an <a href="otl3_exception_class.htm">otl_exception</a> if
there is an SQL error.<br>
<br>
<tt>void syntax_check(const char *sqlstm // SQL Statement<br>
</tt><tt>
);</tt><br>
<tt><br>
</tt></li>
</ul>
<ul>
</ul>
<pre><font size="+2">}; // end of otl_connect</font></pre>
<center>
<hr width="100%">
<p><a href="otl3_bind_variables.htm">Prev</a> <a
href="otl3_exception_class.htm">Next</a><a href="otl3.htm">Contents</a><a
href="home.htm">Go
Home</a></p>
</center>
#define OTL_ODBC_SELECT_STM_EXECUTE_BEFORE_DESCRIBE
href="mailto:skuchin@aceweb.com">skuchin@aceweb.com</a>,
<a href="mailto:skuchin@gmail.com">skuchin@gmail.com</a>.
<script language="JavaScript"><!-- hide from old browsers
var modDate = new Date(document.lastModified)
document.write("<i> Last Updated:</i> " + (modDate.getMonth()+1) + "/" +
modDate.getDate() + "/" + "0"+(modDate.getYear())%100+".");
//-->
</script></p>
<p><i>Permission to use, copy, modify and redistribute this document
for
any purpose is hereby granted without fee, provided that the above
copyright
notice appear in all copies.</i>
</p>
</body>
</html>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -