otl1.htm

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

</xmp>
<li>Construct variable by the name of aname, e.g. ":F1"
<xmp>
otl_variable(const char* aname);
</xmp>
<li>Construct variable/column, with its further use in a select list
in the column_num position.
<xmp>
 otl_variable(const int column_num);
</xmp>
<br>
<hr size=3>
<br>
<li>host varibale of data type T
<xmp>
T v; 
</xmp>
<li>indicator
<xmp>
sb2 ind; 
</xmp>
<li>returned length
<xmp>
ub2 rlen; 
</xmp>
<li>returned code
<xmp>
ub2 rcode; 
</xmp>
</ul>
<xmp>
};
</xmp>
<h3><a name="sec102">Class otl_array</h3>
<p>
This is the OTL template host array class. It is the base class for
constructing specialized template array classes.
</p>
<xmp>
template <class T, int atype, short size>
class otl_array: public otl_generic_variable{
public:
</xmp>
<ul>
<li>Default constructor
<xmp>
otl_array();
</xmp>
<li>Construct array by the name of aname, e.g. ":F1"
<xmp>
otl_array(const char* aname);
</xmp>
<li>Construct array-column, with its further use in a select list in
the column_num position.
<xmp>
otl_array(const int column_num);
</xmp>
<br>
<hr size=3>
<br>
<li>host array
<xmp>
T v[size];
</xmp>
<li>indicator array
<xmp>
sb2 ind[size]; 
</xmp>
<li>returned length array
<xmp>
ub2 rlen[size]; 
</xmp>
<li>returned code array
<xmp>
ub2 rcode[size];
</xmp>
</ul>
<xmp>

};

</xmp>

<h3><a name="sec311">3.1.1. Specialized host variable classes</h3>
<ul>
<li><i><b>Numerical data types</i></b>
<ul>
<li><b>otl_double</b>, <i>example: otl_double f1,f2;</i>
<li><b>otl_float</b>, <i>example: otl_float f1,f2;</i>
<li><b>otl_signed_char</b>, <i>example: otl_signed_char f1,f2;</i>
<li><b>otl_short_int</b>, <i>example: otl_short_int f1,f2;</i>
<li><b>otl_long_int</b>, <i>example: otl_long_int f1,f2;</i>
<li><b>otl_unsigned</b>, <i>example: otl_unsigned f1,f2;</i>
</ul>
</ul>
<ul>
<li><i><b>String data types</i></b>
<ul>
<li><b>otl_cstring</b> <i>example: otl_ctring&ltSTR_SIZE&gt f1,f2;</i>
<li><b>otl_varchar2</b> <i>example: otl_varchar2&ltSTR_SIZE&gt f1,f2;</i>
<li><b>otl_long</b> <i>example: otl_long&ltSTR_SIZE&gt f1,f2;</i>
<li><b>otl_varchar</b>, <i>example: otl_varchar&ltSTR_SIZE&gt f1,f2;</i>
<li><b>otl_varraw</b>, <i>example: otl_varraw&ltSTR_SIZE&gt f1,f2;</i>   
<li><b>otl_raw</b>, <i>example: otl_raw&ltSTR_SIZE&gt f1,f2;</i>      
<li><b>otl_char</b>, <i>example: otl_char&ltSTR_SIZE&gt f1,f2;</i>     
<li><b>otl_charz</b>, <i>example: otl_charz&ltSTR_SIZE&gt f1,f2;</i>    
</ul>
</ul>
<ul>
<li><i><b>Data types for Oracle LONG and LONG RAW columns</i></b>
<p>
These two classes are used for reading and writing objects of the
Oracle LONG and LONG RAW data types. The classes define operator[] to
access elements of the data array, the set_len() function to set up
string length on input and the len() function to get string length on
output.
</p>
<ul>
<li><b>otl_long_varchar</b>, <i>example: otl_long_varchar&ltSTR_SIZE&gt f1,f2;</i>     
<li><b>otl_long_varraw</b>, <i>example: otl_long_varraw&ltSTR_SIZE&gt f1,f2;</i>
</ul>
</ul>

<ul>
<li><i><b>Oracle internal data types (DATE, ROWID, VARNUM, NUMBER)</i></b>
<ul>
<li><b>otl_date</b>, <i>example: otl_date f1,f2;</i>     
<li><b>otl_rowid</b>, <i>example: otl_rowid f1,f2;</i>    
<li><b>otl_varnum</b>, <i>example: otl_varnum f1,f2;</i>   
<li><b>otl_number</b>, <i>example: otl_number f1,f2;</i>   
</ul>
</ul>

<h3><a name="sec312">3.1.2. Specialized host array classes</h3>

<ul>
<li><i><b>Numerical data types</i></b>
<ul>
<li><b>otl_double_array</b>, <i>example: otl_double_array&ltARR_SIZE&gt f1,f2;</i>
<li><b>otl_float_array</b>, <i>example: otl_float_array&ltARR_SIZE&gt f1,f2;</i>
<li><b>otl_signed_char_array</b>, <i>example: otl_signed_char_array&ltARR_SIZE&gt f1,f2;</i>   
<li><b>otl_short_int_array</b>, <i>example: otl_short_int_array&ltARR_SIZE&gt f1,f2;</i>     
<li><b>otl_int_array</b>, <i>example: otl_int_array&ltARR_SIZE&gt f1,f2;</i>   
<li><b>otl_long_int_array</b>, <i>example: otl_long_int_array&ltARR_SIZE&gt f1,f2;</i>      
<li><b>otl_unsigned_array</b>, <i>example: otl_unsigned_array&ltARR_SIZE&gt f1,f2;</i>      
</ul>
</ul>

<ul>
<li><i><b>String data types</i></b>
<ul>
<li><b>otl_ctring_array</b>, <i>example: otl_ctring_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>         
<li><b>otl_varchar2_array</b>, <i>example: otl_varchar2_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>       
<li><b>otl_long_array</b>, <i>example: otl_long_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>   
<li><b>otl_varchar_array</b>, <i>example: otl_varchar_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>        
<li><b>otl_varraw_array</b>, <i>example: otl_varraw_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>         
<li><b>otl_raw_array</b>, <i>example: otl_raw_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>    
<li><b>otl_char_array</b>, <i>example: otl_char_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>   
<li><b>otl_charz_array</b>, <i>example: otl_charz_array&ltARR_SIZE,STR_SIZE&gt f1,f2;</i>          
</ul>
</ul>

<ul>
<li><i><b>Oracle internal data types (DATE, ROWID, VARNUM, NUMBER)</i></b>
<ul>
<li><b>otl_date_array</b>, <i>example: otl_date_array&ltARR_SIZE&gt f1,f2;</i>       
<li><b>otl_rowid_array</b>, <i>example: otl_rowid_array&ltARR_SIZE&gt f1,f2;</i>      
<li><b>otl_varnum_array</b>, <i>example: otl_varnum_array&ltARR_SIZE&gt f1,f2;</i>     
<li><b>otl_number_array</b>, <i>example: otl_number_array&ltARR_SIZE&gt f1,f2;</i>     
</ul>
</ul>

<h2><a name="sec32">3.2. Oracle Call Interface "wrapper"</h2>

<h3><a name="sec103">Class otl_exception</h3>

<p>
This is the OTL exception class. Exceptions of this type are
raised by the library functions (default mode), unless it is
prohibited explicitly in the otl_connect or otl_cursor class
constructors. In case of disabled exceptions OTL functions
return codes and it is the user's responsibility to check out
the codes and handle errors. The main advantage of using
this exception handling mechanism is that exceptions can be
processed in one catch block, instead of checking return
codes from every library function call.
</p>
<xmp>
class otl_exception{
public:
</xmp>
<ul>
<li>This "enum" defines two constants which are used in constructors
of the otl_connect, otl_cursor and otl_select_cursor classes.
<xmp>
enum{ disabled, enabled };
</xmp>
<li>Create exception from LDA
<xmp>
otl_exception(Lda_Def& lda);
</xmp>
<li>Create exception from amsg and acode
<xmp>
otl_exception(const char* amsg,const int acode);
</xmp>
<li>Copy constructor
<xmp>
otl_exception(const otl_exception& p);
</xmp>
<li>Default constructor
<xmp>
 otl_exception();
</xmp>
<br>
<hr size=3>
<br>
<li>error message buffer
<xmp>
unsigned char msg[1000]; 
</xmp>
<li>error code
<xmp>
int code;
</xmp>
</ul>

<xmp>
};

</xmp>

<h3><a name="sec104">Class otl_object</xmp>
<p>
This class is a parent of the otl_cursor and otl_connect
classes. Its children inherit the following two properties: 
<ul>
<li>"connected" flag
<li>"exception enabled" flag
</ul>
<xmp>
class otl_object{
public:
</xmp> 
<ul>
<li>Default constructor
<xmp>
otl_object();
</xmp>
<li>Destructor
<xmp>
virtual ~otl_object();
</xmp>
<br>
<hr size=3>
<br>
<li>"connected" flag
<xmp>
int connected; 
</xmp>
</ul>
<xmp>

protected:

</xmp>
<ul>
<li>"exception enabled" flag
<xmp>
int ex_enabled; 
</xmp>
</ul>
<xmp>

};

</xmp>
<h3><a name="sec105">Class otl_connect</h3>

<p>
This class encapsulates the Oracle Call Interface functions
which have Logon Descriptor Area as their first
parameter. In other words, otl_connect is the class for
creating "connect" objects.
</p>
<xmp>

class otl_connect: public otl_object{
public:

</xmp>
<ul>
<li>Create "connect" object. Exceptions are allowed to raise by
default
<xmp>
otl_connect(int exception_enabled=otl_exception::enabled);
</xmp>
<li>Create "connect" object and connect to Oracle using the
"connect_str" connect string; by default, exceptions are allowed to
raise
<xmp>
 otl_connect(const char* connect_str, 
	     int exception_enabled=otl_exception::enabled 
	    );
</xmp>
<li>Destructor
<xmp>
~otl_connect();
</xmp>
<li>Concurrent logon; OCI application is allowed to have more than one
concurrent logon. Returns 1 on success, 0 on failure.
<xmp>
int rlogon(const char* connect_str);
</xmp>
<li>Get valid LDA from Pro*C. Returns 1 on success, 0 on failure.
<xmp>
int sqllda(void);
</xmp>
<li>Exclusive logon. there may be only one logon of this type
performed in OCI application (for more details see OCI doc.). Returns
1 on success, 0 on failure.
<xmp>
int logon(const char* connect_str);
</xmp>
<li>Disconnect from / log off Oracle. Returns 1 on success, 0 on
failure.
<xmp>
int logoff(void);
</xmp>
<li>Commit current transaction. Returns 1 on success, 0 on failure.
<xmp>
int commit(void);
</xmp>
<li>Roll back current transaction. Returns 1 on success, 0 on failure.
<xmp>
int rollback(void);
</xmp>
<li>Break current OCI call. Returns 1 on success, 0 on failure.
<xmp>
int obreak(void);
</xmp>
<li>Set auto commit mode on. Returns 1 on success, 0 on failure.
<xmp>
int auto_commit_on(void);
</xmp>
<li>Set auto commit mode off. Returns 1 on success, 0 on failure.
<xmp>
int auto_commit_off(void);
</xmp>
<br>
<hr size=3>
<br>
<li>Logon Descriptor Area
<xmp>
Lda_Def lda; 
</xmp>
<li>reference to "V7 return code"
<xmp>
ub2& rc; 
</xmp>
</ul>
<xmp>

};

</xmp>
<h3><a name="sec106">Class otl_column_desc</h3>

This class is data structure which contains a select item
(column) descriptive information. The information may be
obtained by the otl_cursor::describe_column function call
(see the otl_cursor class).
<xmp>
class otl_column_desc{
public:
</xmp>
<ul>
<li>field name
<xmp>
sb1  name[241]; 
</xmp>
<li>field name length
<xmp>
sb4  nlen;      
</xmp>
<li>field size as the field is represented inside ORACLE 
<xmp>
sb4  dbsize;    
</xmp>
<li>internal datatype code
<xmp>
sb2  dbtype;    
</xmp>
<li>numeric field scale: NUMBER(scale,precision)
<xmp>
sb2  scale;     
</xmp>
<li>numeric field precision
<xmp>
sb2  prec;      
</xmp>
<li>maximum display size of the field
<xmp>
sb4  dsize;     
</xmp>
<li>NULLs are allowed 
<xmp>
sb2  nullok;    
</xmp>
</ul>
<xmp>

};

</xmp>

<h3><a name="sec107">Class otl_cursor</h3>
<p>
This class is a general-purpose cursor class.
</p>
<xmp>
class otl_cursor: public otl_object{
public:
</xmp>
<ul>
<li>Create "cursor" object. by default, exceptions are allowed to
raise.
<xmp>
otl_cursor(int exception_enabled=otl_exception::enabled);
</xmp>
<li>Create "cursor" object and open cursor via  "connect"
<xmp>
otl_cursor(otl_connect& connect, // reference to "connect" object
	   int exception_enabled=otl_exception::enabled
	  );
</xmp>
<li>Close cursor (if opened) and destruct object
<xmp>
~otl_cursor();
</xmp>
<li>Open cursor via "connect". Returns 1 on success, 0 on failure
<xmp>
int open(otl_connect& connect);
</xmp>

<li>Close cursor. Returns 1 on success, 0 on failure
<xmp>
int close(void);
</xmp>
<li>Cancel a query after desired number of rows have been
fetched. Returns 1 on success, 0 on failure
<xmp>
int cancel(void);
</xmp>
<li>Set rollback options for non-fatal Oracle errors. For more info
see the OCI manual, the "oopt" function. Returns 1 on success, 0 on
failure
<xmp>
int option(int rbopt, int waitopt);
</xmp>
<li>Fetch a portion of a LONG or LONG RAW column. For more info see the
OCI manual, the "oflng" function. Returns 1 on success, 0 on failure
<xmp>
int fetch_long(int column_num, // column number: 1,2,...
	       void* buf, // pointer to buffer
	       sb4 bufl, // buffer size
	       int dtype, // buffer data type, see ext* "enum"
	       ub4* retl, // returned length
	       sb4 offset // offset
	      );
</xmp>
<li>Parse sql statement. Returns 1 on success, 0 on failure
<xmp>
int parse(const char* sqlstm);
</xmp>
<li>Parse sql statement; bind variable and select list items; variable
list needs to be terminated with 0 pointer; Returns 1 on success, 0 on
failure. if variable list contains variables which are SELECT statement
output columns and if the variables don't have "column_num"
defined, then the parse function enumerates the variables as follows:<br><br>
<ul>
<li>eparse("select...",&f1,&f2,&f3,0);<br><br>
<ul>
<li>f1 -- column 1
<li>f2 -- column 2
<li>f3 -- column 3
</ul>
</ul><br>
<xmp>
int eparse(const char* sqlstm,...);
</xmp>
<li>Execute statement iters times. Returns 1 on success, 0 on failure
<xmp>
int exec(short iters=1);
</xmp>
<li>Combined operation: Parse+Bind+Execute. Parse sqlstm. Bind
variables. Execute statement iters times.  Returns 1 on success, 0 on
failure
<xmp>
int exec(const char* sqlstm, // SQL statement
	 short iters,  // number of iterations
	 ... // NULL terminated host variable list
        );
</xmp>

<li>Fetch iters number of rows. Returns 1 on success, 0 on failure
<xmp>
int fetch(short iters=1);
</xmp>
<li>Combined operation -- execute statement + fetch iters number of
rows. Returns 1 on success, 0 on failure
<xmp>
int exfet(short iters=1);
</xmp>
<li>Functions to bind placeholders<br><br>
<ul>
<li>Bind host variable/array (instantiated template) to
placeholder. Returns 1 on success, 0 on failure
<xmp>
int bind(const char* name, 
            // placeholder name: ":F1", ":F2"
	 otl_generic_variable& v 
	    // reference to host variable/array
        );
</xmp>
<li>Bind "ordinary" host variable/array to placeholder. Returns 1 on
success, 0 on failure
<xmp>
int bind(const char* name, // placeholder name: ":f1