OTL 4.0, OTL reference cursor stream class

OTL reference cursor stream class

This class (otl_refcur_stream) is used for reading rows from a reference cursor bind variable. The class is defined for OTL/OCI8/8i/9i/10g only. It's similar to the otl_stream class itself, when the otl_stream is instantiated with a SELECT statement, or with a single reference cursor. otl_refcur_stream can be initiliazed by reading a reference cursor descriptor from an otl_stream. The class, in tandem with the refcur placeholder, allows the otl_stream to return multiple reference cursors from a stored procedure call in one shot.

Potentially, the otl_refcur_stream class may raise an OTL defined exception.

All of the functions, defined in this class, mimick the otl_stream functions, therefore, see the descriptions of the corresponding functions in otl_stream.

class otl_refcur_stream {
public:

 void set_column_type(const int column_ndx,
                      const int col_type,
                      const int col_size=0);
 void set_all_column_types(const unsigned mask=0);

 void rewind(void);
 int is_null(void);
 int eof(void);
 void close(void);

 otl_column_desc* describe_select(int& desc_len);

 otl_var_desc* describe_out_vars(int& desc_len);
 otl_var_desc* describe_next_out_var(void); 

 otl_refcur_stream& operator>>(char& c);
 otl_refcur_stream& operator>>(unsigned char& c);
 otl_refcur_stream& operator>>(char* s);
 otl_refcur_stream& operator>>(unsigned char* s);
 otl_refcur_stream& operator>>(int& n);
 otl_refcur_stream& operator>>(unsigned& u);
 otl_refcur_stream& operator>>(short& sh);
 otl_refcur_stream& operator>>(long int& l);
 otl_refcur_stream& operator>>(float& f);
 otl_refcur_stream& operator>>(double& d);

 otl_refcur_stream& operator>>(OTL_BIGINT& n);
     // Reads a string (char) value from the stream and converts it to
     // a signed 64-bit integer. This operator is useful for reading 
     // large whole numbers that are larger than the "double"
     // container can hold. The underlying SELECT statement that gets returned
     // to C++ via a reference cursor should explicitly convert numeric values
     // to strings, for example: LTRIM(TO_CHAR(my_large_num))

 otl_refcur_stream& operator>>(otl_long_string& s); // read the LOB from the stream
 otl_refcur_stream& operator>>(otl_datetime& dt); // read date/time info from the stream
 otl_refcur_stream& operator>>(otl_lob_stream& lob); 
                      // read reference to CLOB/BLOB from otl_ref_stream 
                      // into otl_lob_stream (OCI8). In other words,
                      // initialize otl_lob_stream for reading CLOB/BLOB 
                      // in stream mode
 otl_refcur_stream& operator>>(std::string& s); 
   // Read the ANSI C++ std::string. This operator can
   // read VARCHAR/CHAR table fields as well as large string
   // objects (TEXT, LONG, CLOB, etc.)

If #define OTL_UNICODE is enabled, the following operators have 
special meaning:

  otl_stream& operator>>(unsigned char* s);
       // returns a null terminated array of unsigned short's
       // (double-byte Unicode characters). Therefore, "unsigned char*" 
       // needs to be type cast to "unsigned short*". Also, it's recommended
       // to allocate 2 bytes per each Unicode character. plus 2 bytes per 
       // possible surrogate character.

  otl_stream& operator>>(otl_long_unicode_string& s); 
      // read the Unicode LOB from the stream

}; // end of otl_refcur_stream

Prev Next Contents Go Home

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.