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: LONG, RAW, LONG RAW; CLOB, BLOB
MS SQL Server: TEXT, IMAGE, VARBINARY, BINARY
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 datatypes:

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 datatypes)
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 datatypes 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 datatypes 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:

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

     unsigned char* v;

General constructor. It creates an otl_long_string instance: allocates memory for the LOB buffer and sets internal variables. The buffer_size parameter defines the size of the LOB buffer. By default, the size is 32760. 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.

input_length

set_len

     otl_long_string(const int buffer_size=32760,
                     const int input_length=0
                    );

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 opeations with LOBs.

The buffer_size parameter defines the size of the external buffer for the otl_long_string.

The input_length parameter 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.

     otl_long_string(const void* external_buffer,
                     const int buffer_size,
                     const int input_length=0
                    );

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

     void set_len(const int len=0);

When an otl_long_string is used with an otl_lob_stream and OTL/OCI8i/9i/10g, 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 haev any effect.

void set_last_piece(const bool last_piece=false);

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

     int len(void);

This operator allows the user to access individual bytes of the LOB.

     unsigned char& operator[](int ndx);

Assignment operator

otl_long_string& operator=(const otl_long_string&);

Copy constructor

otl_long_string(const otl_long_string&);

}; // end of otl_long_string

class otl_long_unicode_string: public otl_long_string{
public:

General constructor. It creates an otl_long_unicode_string instance: allocates memory for the LOB buffer and sets internal variables. The buffer_size parameter defines the size of the LOB buffer. 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 accomodate a possible surrogate character).

input_length

set_len

     otl_long_unicode_string(const int buffer_size=32760,
                             const int input_length=0
                            );

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 opeations with LOBs.

buffer_size

The input_length parameter 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.

     otl_long_unicode_string(const void* external_buffer,
                             const int buffer_size,
                             const int input_length=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

     void set_len(const int len=0);

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

     int len(void);

This operator allows the user to access individual Unicode characters of the LOB.

     unsigned short& operator[](int ndx);

}; // 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.