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:
As opposed to normal dataypes of columns in tables, the above LOBs
can be set to NULL in two ways: either writing otl_null()
into the otl_stream or setting the length of the LOB to 0 by calling
otl_long_string::set_len(0)
and the writing the LOB into the otl_stream.
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 input, behavior of Oracle's CLOBs and BLOBs is the same as the
other LOB datatypes, that is otl_null() or set_len(0) can be used when
writing a CLOB or BLOB into the database.
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.
The input_length parameter 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.
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);
}; // 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).
The input_length parameter 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.
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.
The buffer_size parameter defines the size of the external
buffer
for the otl_long_unicode_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_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 NextContentsGo
Home
Copyright © 1996, 2007, Sergei Kuchin, email: skuchin@ispwest.com,
skuchin@gmail.com
.
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.