OTL 4.0, OTL Long String class

OTL Long String class

This class is used in operations with Large Objects (LOB). In OTL 4.0, the otl_long_string can hold a LOB of any type:

Oracle 7: LONG, LONG RAW
Oracle 8: LONG, LONG RAW; CLOB, BLOB
MS SQL Server, Sybase: TEXT, IMAGE
DB2: CLOB, BLOB

OTL 4.0 defines the following bind variable datatypes for manipulating LOBs:

varchar_long for Oracle 7/8 LONG, MS SQL Server/Sybase TEXT, DB2 CLOB
raw_long for Oracle 7/8 LONG RAW, MS SQL Server/Sybase IMAGE, DB2 BLOB
clob for Oracle 8 CLOB
blob for Oracle 8 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'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's CLOB, Oracle 8'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_string_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);

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

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.