OTL 4.0, OTL Long String, Long Unicode String classes

OTL Long String, Long Unicode String classes

These classes are used in operations with Large Objects (LOB). In OTL 4.0, otl_long_string can hold a LOB of any type as well as RAW / BINARY:

Oracle 7: LONG, RAW, LONG RAW
Oracle 8, 8i, 9i, 10g, 11g: LONG, RAW, LONG RAW; CLOB, BLOB
MS SQL Server: TEXT, IMAGE, VARBINARY, BINARY, VARCHAR(MAX), VARBINARY(MAX)
DB2: CLOB, BLOB
Sybase: TEXT, IMAGE, VARBINARY, BINARY
PostgreSQL: TEXT, BYTEA,
SAP/MAX DB: CHAR() BYTE, VARCHAR() BYTE, LONG VARCHAR, LONG VARCHAR BYTE
MySQL: LONGTEXT, LONGBLOB, VARBINARY, BINARY

otl_long_unicode_string is specialized for Unicode character based large strings. otl_long_unicode_string can hold the following data types:

Oracle 8i, 9i, 10g: LONG, CLOB; the database default character set may be set to ASCII, or UTF-8, etc
Oracle 8i, 9i, 10g: NCLOB; the database national character set may be set to whatever is allowed for a concrete version of the database (8i and 9i/10g differ / are not the same in that regard, as far as supporting different versions of Unicode, and what sets are allowed for national character data types)
MS SQL NTEXT
DB2 CLOB / DBCLOB when the database supports Unicode (UTF-8, UCS-2, etc.)

In the case if Unicode OTL is enabled by #define OTL_UNICODE, otl_long_string needs to be used for Oracle LONG RAWs, BLOBs, MS SQL IMAGEs, DB2 BLOBs, etc (large binary strings, generally speaking), because they still remain the large byte strings, without any character semantic attached.

OTL 4.0 defines the following bind variable data types for manipulating LOBs:

varchar_long for Oracle 7/8/8i/9i/10g LONG, MS SQL Server/Sybase TEXT/NTEXT, DB2 CLOB/DBCLOB
raw_long for Oracle 7/8/8i/9i/10g RAW, LONG RAW, MS SQL Server/Sybase IMAGE, DB2 BLOB
clob for Oracle 8/8i/9i/10g CLOB, NCLOB (if #define OTL_UNICODE is enabled).
blob for Oracle 8/8i/9i/10g BLOB

Large Objects (LOBs) and NULLs

Behavior of LOBs is slightly different from the other table column data types as far as NULLs are concerned:

Oracle 7/8/8i/9i/10g's LONG, Oracle 7/8's LONG RAW, MS SQL Server/Sybase's TEXT, MS SQL Server/Sybase's IMAGE, DB2's CLOB/BLOB:

otl_null

set_len

On the output, when the LOB is being read from the otl_stream, the checking for the NULL value can be done in two ways: either by calling otl_stream::is_null() or by calling otl_long_string::len() and checking if it returns 0.

Oracle 8/8i/9i/10g's CLOB, Oracle 8/8i/9i/10g's BLOB:

On the output, when the Oracle 8 CLOB/BLOB is being read from the otl_stream, the checking for the NULL value can be done only in one way by calling otl_long_string::len() and checking if it returns 0. The otl_stream::is_null() function always returns 0 for CLOBs/BLOBs. So, it is recommended to use the len() function and check it for 0 instead of using is_null().

class otl_long_string{
public:

Function / data member

Description

unsigned char* v;

Pointer to the LOB value. In other words, the field is a pointer to the LOB buffer.

otl_long_string(...);

Parameter	Description
const int buffer_size=32760	It defines the size of the LOB buffer. By default, the size is 32760.
const int input_length=0	It defines the actual length of the string on the input. If this parameter is used, then the set_len() function does not need to be called.

General constructor. It creates an otl_long_string instance: allocates memory for the LOB buffer and sets internal variables. In addition to setting the size of otl_long_string, the otl_connect::set_max_long_size() needs to be called with the same or a greater size.

otl_long_string(...);

Parameter	Description
const void* external_buffer	Pointer to an external buffer
const int buffer_size	Buffer size defines the size of the external buffer for the otl_long_string.
const int input_length=0	Input length is the actual length of the string on the input. If this parameter is used, then there is no need to call the set_len() function.

General constructor. It creates an otl_long_string instance: it sets the v field to the value of external_buffer and sets internal variables. In case if this constructor is called, memory for the LOB buffer is not allocated, the address of an external buffer is used instead. This constructor is provided for more efficient manipulation of LOBs. If it is critical for performance or memory reasons, this constructor can be used for passing the address of a user defined buffer into the otl_stream operations with LOBs.

void set_len(const int len=0);

This function sets the dynamic length of the LOB. The function needs to be called before writing the LOB into the otl_stream.

void set_last_piece
(const bool last_piece=false);

When an otl_long_string is used with an otl_lob_stream and OTL/OCI8i/9i/10g/11g, this function indicates that the otl_string_string is the last piece / chunk in a sequence of LOB chunks being written into the otl_lob_stream. The function exists for OTL/ODBC/DB2-CLI but it does not have any effect.

int len();

This function returns the dynamic length of the LOB. The function needs to be called after reading the LOB from the otl_stream

unsigned char& operator[](int ndx);

const unsigned char& operator[](int ndx) const;

These operators allow the user to access individual bytes of the LOB.

otl_long_string& operator=
(const otl_long_string&);

Assignment operator

otl_long_string
(const otl_long_string&);

Copy constructor

}; // end of otl_long_string

class otl_long_unicode_string: public otl_long_string{
public:

Function / data member

Description

otl_long_unicode_string(...);

Parameter	Description
const int buffer_size=32760	defines the size of the LOB buffer.
const int input_length=0	defines the actual length of the string on the input. If this parameter is used, then the set_len() function does not need to be called.

General constructor. It creates an otl_long_unicode_string instance: allocates memory for the LOB buffer and sets internal variables. By default, the size is 32760 Unicode characters. In addition to setting the size of otl_long_unicode_string, the otl_connect::set_max_long_size() needs to be called with the same or a greater size.Note: all sizes for Unicode strings are given not in bytes but in Unicode characters (2 bytes per character times 2 to accommodate a possible surrogate character).

otl_long_unicode_string(...);

Parameter	Description
const void* external_buffer	Pointer to the external buffer
const int buffer_size	defines the size of the external buffer for the otl_long_unicode_string.
const int input_length=0	the actual length of the string on the input. If this parameter is used, then there is no need to call the set_len() function.

General constructor. It creates an otl_long_unicode_string instance: it saves the value of external_buffer and sets internal variables. In case if this constructor is called, memory for the LOB buffer is not allocated, the address of an external buffer is used instead. This constructor is provided for more efficient manipulation of LOBs. If it is critical for performance or memory reasons, this constructor can be used for passing the address of a user defined buffer into the otl_stream operations with LOBs.

void set_len(const int len=0);

This function sets the dynamic length of the LOB in Unicode characters (2 bytes per each). The function needs to called before writing the LOB into the otl_stream

int len(void);

This function returns the dynimac length of the LOB in Unicode characters (2 bytes per character). The function needs to be called after reading the LOB from the otl_stream

unsigned short& operator[](int ndx);

const unsigned short& operator[](int ndx) const;

These operators allow the user to access individual Unicode characters of the LOB.

otl_long_unicode_string& operator=
(const otl_long_unicode_string&);

Assignment operator

otl_long_unicode_string
(const otl_long_unicode_string&);

Copy constructor

}; // end of otl_long_unicode_string

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.