OTL 4.0, OTL LOB stream class

OTL LOB stream class

This class is used for reading / writing Large Objects (Oracle 8/8i/9i/10g/11g's [N]CLOBs/BLOBs, DB2's CLOBs/BLOBs, MS SQL Server's TEXT/IMAGE, MS SQL Server 2005/2008's VARCHAR(MAX) / VARBINARY(MAX) / NVARCHAR(MAX), MySQL's LONGTEXTs/LONGBLOBs, Sybase's (via ODBC) TEXTs/IMAGEs) in the stream mode. The stream mode allows an unlimited number of bytes to be read/written, regardless of the buffer size.

otl_lob_stream does not have any specific constructor by which an actual instance of otl_lob_stream can be created. Instead, the stream gets initialized by writing / reading an otl_lob_stream variable to / from the otl_stream.

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

class otl_lob_stream {
public:

Function / data member	Description
void set_len(const int alen);	Sets the total number of bytes (or Unicode characters) to be written to the otl_lob_stream. In other words, set the total size of the LOB. The total length of the LOB normally needs to set before the first LOB chunk should be written into the otl_lob_stream. However, OTL 4.0.138 and higher does not require that. OTL/ODBC/DB2-CLI completely relaxes that requirement. OTL/OCI8i/9i/10g/11g does not require that, if the last LOB chunk / piece in the sequence is indicated through a call to otl_long_string::set_last_piece(true).
otl_lob_stream& operator<< (const std::string& s);	Writes the whole CLOB / TEXT / VARCHAR(MAX), etc. into the stream. Declared, when OTL_STL is defined and OTL_UNICODE is not defined. Also, this function can write BLOB / VARBINARY(MAX), etc. into the stream, even if the string has 0 bytes ('\0') in it.
otl_lob_stream& operator<< (const ACE_TString& s);	Writes the whole CLOB / TEXT / VARCHAR(MAX), etc. into the stream. Declared, when OTL_ACE is defined and OTL_UNICODE is not defined. Also, this function can write BLOB/ VARBINARY(MAX), etc. into the stream, even if the string has 0 bytes ('\0') in it.
otl_lob_stream& operator>>(std::string& s);	Reads the whole CLOB / TEXT / etc. from the stream into a string Declared, when OTL_STL is defined and OTL_UNICODE is not defined. Also, OTL 4.0.264 and higher can read BLOB / VARBINARY(MAX), etc. values from the stream, even if the values contain 0 bytes ('\0) in them.
otl_lob_stream& operator>> (ACE_TString& s);	Reads the whole CLOB / TEXT / etc. from the stream into a string Declared, when OTL_ACE is defined and OTL_UNICODE is not defined Also, OTL 4.0.264 and higher can read BLOB / VARBINARY(MAX), etc. values from the stream, even if the values contain 0 bytes ('\0) in them.
void setStringBuffer (const int chunk_size);	Sets an internal buffer of "chunk_size" to help reduce the number of calls to string::append in the operators >>() above. The bigger the buffer, the fewer the calls to the append() to concatenate chunks of the CLOB/BLOB value to the output string.
otl_lob_stream& operator<< (const otl_long_string& s);	Writes a chunk of the LOB into the stream.
otl_lob_stream& operator<< (const otl_long_unicode_string& s);	Writes a chunk of the Unicode LOB into the stream. Declared, when OTL_UNICODE is defined
otl_lob_stream& operator>> (otl_long_string& s);	Reads a chunk of LOB from the stream.
otl_lob_stream& operator>> (otl_long_unicode_string& s);	Reads a chunk of Unicode LOB from the stream. Declared, when OTL_UNICODE is defined.
int len();	Gets the length of the LOB to be read in bytes, or in Unicode characters.. In OTL/OCI8/8i/9i, the actual length of the LOB is available immediately after the initialization of the stream. In OTL/ODBC and OTL/DB2-CLI, the function returns 0 before the first chunk of the LOB is read, and it returns the actual length of the LOB after the first chunk of the LOB is read. This difference is due to the differences in behavior of the underlying database APIs. So, for writing portable [across multiple databases] code, it is recommended to use this function carefully.
int eof();	Checks the stream for "end-of-file" condition
void close (bool dont_throw_size_doesnt_match_exception=false);	Closes the stream. When the function's only parameter is set to true, the function doesn't throw "size doesn't match" otl_exception under OTL/OCIx, where x>=8 (OCI 8 and higher).
bool is_initialized();	Checks if the LOB in the stream is initialized or not. Say, an Oracle PL/SQL block binds an output :f2<clob>, and, when the block gets executed, the actual CLOB doesn't get initialized. The function will return false in this case.
`void setInitialReadOffset(const int initial_offset);`	This function is available when OTL is used with Oracle only. The function sets the initial offset (0 based: 0,1...) for reading a CLOB/BLOB. The function should be called after the otl_lob_stream is initialized with otl_stream::operator>>(otl_lob_stream&) and before the first read operation on the CLOB/BLOB, for example: `s>>lob; ...` `lob.setInitialReadOffset(30000);` `...` `lob>>f2; // reading a chunk of BLOB`
`#if defined (OTL_STD_STRING_VIEW_CLASS)otl_lob_stream& operator<< (OTL_STD_STRING_VIEW_CLASS s);#endif`	This operator << allows otl_lob_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.

}; // end of otl_lob_stream

The ODBC as well as DB2 CLI standards recommend that LOBs should be put at the end of INSERT/SELECT statements. For example:

INSERT INTO my_tab (f1,f2,f3_lob,f4_lob)...
SELECT f1,f2,f3_lob,f4_lob FROM my_tab...

The recommendation applies especially in the case of piece-wise data operations, that is, in the OTL LOB stream mode. At the same time, the standards say that it is up to the ODBC drivers/database APIs to either enforce or not to enforce that rule. The LOB's part of OCI8 in Oracle does not require that kind of thing, so it is really up to the developer to decide what to do. However, the general recommendation for writing portable code, that uses the LOB stream mode, would be to put LOBs at the end of the column lists in INSERT or SELECT statements.

In order to use the otl_lob_stream class for OTL/ODBC and OTL/DB2-CLI, a call to otl_stream::set_lob_stream_mode() is required.

Also, see example 56, 57, 122, 123, 124, 125, 126, 127, 128, 129.

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.