Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages
SQLDBC::SQLDBC_LOB

SQLDBC::SQLDBC_LOB Class Reference

List of all members.

Detailed Description

Interface to a large object (LOB).

Definition at line 390 of file SQLDBC.h.

Public Member Functions

Member Function Documentation

SQLDBC_Retcode SQLDBC::SQLDBC_LOB::close (   ) 
 

Closes the LOB object.

No further actions can take place.

SQLDBC_Retcode SQLDBC::SQLDBC_LOB::getData (  void *  paramAddr,
SQLDBC_Length *  LengthIndicator,
const SQLDBC_Length  Size,
const SQLDBC_Length  position,
const SQLDBC_Bool  Terminate = SQLDBC_TRUE
) 
 

Retrieves the content of the specified LOB column.

The specified LOB column value is converted to the given length and to the output parameter buffer pointed to paramAddr. After the operation, the internal position is the start position plus the number of characters that have been read.

Parameters:
paramAddr A pointer to the parameters output buffer.
LengthIndicator [out] Pointer to a variable that stores the column length or the indicator value SQLDBC_NULL_DATA if the column contains the NULL value. For character data it contains on success the number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator, if the Terminate flag was set. If the source string exceeds the Size value SQLDBC_DATA_TRUNC will be returned and LengthIndicator is set to the number of bytes (except the terminator bytes) needed to copy without truncation.
Size [in] Length of the parameter buffer in bytes. For character data the Size argument must be large enough to store the terminator byte(s) if the Terminate flag is set.
position The start position from where to read.
Terminate [in] Specifies that the output buffer must be finished with a C-style zero-terminator. The Terminate flag works only for the host variable type character (ASCII, UCS2 or UTF8). As a default, all character data is zero-terminated.
Returns:
SQLDBC_OK on success SQLDBC_DATA_TRUNC if the output buffer was too small. SQLDBC_NO_DATA_FOUND if the complete LOB value has been read, or if the given position is outside the boundaries of the value. SQLDBC_NOT_OK if a database access or conversion error occurred. In this case an error is set in the result set/prepared statement that is related to this object.

SQLDBC_Retcode SQLDBC::SQLDBC_LOB::getData (  void *  paramAddr,
SQLDBC_Length *  LengthIndicator,
const SQLDBC_Length  Size,
const SQLDBC_Bool  Terminate = SQLDBC_TRUE
) 
 

Retrieves the content of the specified LOB column.

The specified LOB column value is converted to the given length and to the output parameter buffer pointed to paramAddr. Repeated calls of this method proceed with reading the LOB value, as long as there is data to read available.

Parameters:
paramAddr A pointer to the parameters output buffer.
LengthIndicator [out] Pointer to a variable that stores the column length or the indicator value SQLDBC_NULL_DATA if the column contains the NULL value. For character data it contains on success the number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator, if the Terminate flag was set. If the source string exceeds the Size value SQLDBC_DATA_TRUNC will be returned and LengthIndicator is set to the number of bytes (except the terminator bytes) needed to copy without truncation.
Size [in] Length of the parameter buffer in bytes. For character data the Size argument must be large enough to store the terminator byte(s) if the Terminate flag is set.
Terminate [in] Specifies that the output buffer must be finished with a C-style zero-terminator. The Terminate flag works only for the host variable type character (ASCII, UCS2 or UTF8). As a default, all character data is zero-terminated.
Returns:
SQLDBC_OK on success SQLDBC_DATA_TRUNC if the output buffer was too small. SQLDBC_NO_DATA_FOUND if the complete LOB value has been read. SQLDBC_NOT_OK if a database access or conversion error occurred. In this case an error is set in the result set/prepared statement that is related to this object.

SQLDBC_Length SQLDBC::SQLDBC_LOB::getLength (   ) 
 

Retrieves the length of this LOB in the database.

The length is returned in chars. The LOB must be opened for reading to retrieve this value.

Returns:
The length of the LOB in the database, or -1 if that information is not available. If the LOB is a NULL value, 0 is returned.

SQLDBC_Length SQLDBC::SQLDBC_LOB::getPosition (   ) 
 

Get the current read/write position.

Returns:
The current read/write position in characters. The read/write position starts with 1. If there is no position available, 0 is returned.

SQLDBC_Length SQLDBC::SQLDBC_LOB::getPreferredDataSize (   ) 
 

Retrieves the optimal size of data for reading or writing (the maximum size that can be transferred with one call to the database server).

An application may use this to optimize the communication, by using buffers that are multiples of the preferred size.

Returns:
The optimal data size, or 0 if this size is not available (because the LOB is closed).

SQLDBC_Retcode SQLDBC::SQLDBC_LOB::putData (  void *  paramAddr,
SQLDBC_Length *  paramLengthIndicator
) 
 

Put data into a LOB value that is referenced by this LOB object.

Parameters:
paramAddr Pointer to the data which is to be assigned to the LOB value. The type of the data
paramLengthIndicator [in] Pointer to parameter length or indicator.
Returns:
See also:
nextParameter

SQLDBC_Retcode SQLDBC::SQLDBC_LOB::setKeepAlive (  SQLDBC_Bool  keepalive  ) 
 

Sets the keepalive behaviour of an existing LOB.

A LOB is usually kept open for reading as long as there is no navigation on the result set that leads to an invalidation of the current row set. If the flag is set to true, the LOB will be kept alive until it is explicitely closed, the cursor is closed, or a transaction command (commit/rollback) is issued.

Parameters:
keepalive Whether the LOB should be kept. If it is set to and the LOB is already kept over its usual lifetime (see above), it is closed immediately.
Returns:
SQLDBC_OK on success, SQLDBC_NOT_OK on error, e.g. when the LOB is already closed, or the LOB was opened for writing.