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, mimic the otl_stream functions, therefore, see the descriptions of the corresponding functions in otl_stream.

class otl_refcur_stream {
public:

Function Description

void set_column_type(...);

Parameter	Description
const int column_ndx	relative index of the columns in the query: 1,2,3...
const int col_type	one of the data type constants, defined by OTL.
const int col_size=0	size, associated with the new data type of the column. It has be to specified for the otl_var_char type only. Sizes of all numeric types are calculated.

Sets a SELECT output column data type. In other words, override the default mapping of output column data types.

This function can be called for straight SELECT statements (both Oracle and ODBC), referenced cursor SELECT statements (Oracle), and implicit SELECT statements / result sets (ODBC for MS SQL Server and Sybase).

void set_all_column_types(const unsigned mask=0);

Sets data types of a group of SELECT output columns. This function can override data types of column groups: all numeric columns to string, all date columns to string, or the combination of both. amask parameter can be set to the following values:

otl_all_num2str, e.g.: set_all_column_types(otl_all_num2str);
otl_all_date2str, e.g.: set_all_column_types(otl_all_date2str);
otl_all_num2str | otl_all_date2str, e.g.: set_all_column_types(otl_all_num2str | otl_all_date2str);

int is_null();

Tests if NULL was fetched from the stream.

int eof();

Tests if all data has been already read from the stream. This function has the same meaning as the eof() funtion in C++ streams

void skip_to_end_of_row() Skips to the end of the current row, for example:

while(!s.eof()){
s>>f1;
...
s.skip_to_end_of_row();
...
}

otl_refcur_stream sets the internal pointers to the "end of the current row", so that the next call to operator >> will fetch the first value of the next logical row, or reach the end of the fetch sequence.

void close();

Closes the stream.

otl_column_desc* describe_select(int& desc_len);

Describes the output columns of the reference cursor.

otl_var_desc* describe_out_vars(int& desc_len);

Describes stream's output bind variables.

otl_var_desc* describe_next_out_var(void);

Describes the next output bind variable.

otl_refcur_stream& operator>>(char& c);

reads a single one-byte character

otl_refcur_stream& operator>>(unsigned char& c);

reads a single one-byte unsigned character

otl_refcur_stream& operator>>(char* s);

reads a string of one-byte characters

otl_refcur_stream& operator>>(unsigned char* s);

reads a string of one-byte unsigned characters

otl_refcur_stream& operator>>(int& n);

reads a signed 32-bit integer

otl_refcur_stream& operator>>(unsigned& u);

reads an unsigned 32-bit integer

otl_refcur_stream& operator>>(short& sh);

reads a signed 16-bit integer

otl_refcur_stream& operator>>(long int& l);

reads a signed long integer (32, or 64-bit, depending on whether it's a 32-bit, LLP64 or LP64 platform)

otl_refcur_stream& operator>>(float& f);

reads a 4-byte floating point value

otl_refcur_stream& operator>>(double& d);

reads an 8-byte floating point value

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);

Reads the LOB from the stream

otl_refcur_stream& operator>>(otl_datetime& dt);

Reads date/time from the stream

otl_refcur_stream& operator>>(otl_lob_stream& lob);

Reads reference to CLOB/BLOB from otl_refcur_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);

Under #define OTL_STL

Reads the ANSI C++ std::string. This operator can read VARCHAR/CHAR table fields as well as large string objects (TEXT, LONG, CLOB, etc.)

otl_refcur_stream& operator>>(ACE_TString& s);

Under #define OTL_ACE

Reads the ACE_TString. This operator can read VARCHAR/CHAR table fields as well as large string objects (TEXT, LONG, CLOB, etc.)

otl_refcur_stream& operator>>(unsigned char* s);

Under #define OTL_UNICODE

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_refcur_stream& operator>>(otl_long_unicode_string& s);

Under #define OTL_UNICODE

Reads the Unicode LOB from the stream

otl_refcur_stream& operator>>(OTL_UNICODE_CHAR_TYPE* s);

Under #define OTL_UNICODE_CHAR_TYPE

Reads a NULL terminated string of Unicode characters

otl_refcur_stream& operator>>(OTL_UNICODE_STRING_TYPE& s);

Under #define OTL_UNICODE_STRING_TYPE

Reads an std::string compliant (by interface) string of OTL_UNICODE_STRING_TYPE

otl_refcur_stream& operator>> (oci_spatial_geometry& g); otl_refcur_stream& operator<< (const oci_spatial_geometry& g); Under #define OTL_ORA_SDO_GEOMETRY, operators for reading / writing MDSYS.SDO_GEOMETRY values from / to the following OTL defined container: oci_spatial_geometry.

For more detail on MDSYS.SDO_GEOMETRY, see the corresponding Oracle manual.

#if defined (OTL_STD_STRING_VIEW_CLASS)otl_refcur_stream& operator<< (OTL_STD_STRING_VIEW_CLASS s);#endif This operator << allows otl_refcur_stream to be used with std::string_view or std::experimental::string_view classes. std::string_view is a replacement for read only std::string / "const std::string&" in C++17 standard.

#if defined (OTL_STD_UNICODE_STRING_VIEW_CLASS)otl_refcur_stream& operator<< (OTL_STD_UNICODE_STRING_VIEW_CLASS s);#endif This operator << allows otl_refcur_stream to be used with std::basic_string_view or std::experimental::basic_string_view classes. std::basic_string_view is a replacement for read only standard strings in C++17 standard.

}; // 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. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.