odbx_lo_read(3)

NAME
odbx_lo_read - Reads content from a large object

SYNOPSIS
\FC#include <opendbx/api.h>\F[]

\FCssize_t odbx_lo_read\F[]
\FC(odbx_lo_t* lo, void* buffer, size_t buflen);\F[]

DESCRIPTION
To get the content of a large object, \FCodbx_lo_read\F[]() fetches the data in one or more pieces from the server and stores it into the user supplied \FCbuffer\F[]. After opening the large object using \FCodbx_lo_open\F[](), the first call to \FCodbx_lo_read\F[]() will return the bytes from the beginning. The second and all other calls will store subsequent parts of the large object content into the \FCbuffer\F[] until the end of the data is reached. To reread the content a second time, you have to close the large object handle and reopen it again as some databases provide no way to reposition the internal file position indicator for the stream.

The \FClo\F[] parameter has to be the large object handle created and returned by \FCodbx_lo_open\F[]() via its second parameter. It becomes invalid after it was supplied to \FCodbx_lo_close\F[]() and this function will return an error in this case. The large object content fetched from the server is stored into the user supplied \FCbuffer\F[] up to \FCbuflen\F[] bytes.

RETURN VALUE
\FCodbx_lo_read\F[]() returns the number of bytes placed into \FCbuffer\F[], which may be up to \FCbuflen\F[] bytes. If the end of the content is reached and no more data is available, the return value will be 0. On error, a code whose value is less than zero is returned if one of the operations couldn't be completed successfully. Possible error codes are listed in the error section and they can be feed to \FCodbx_error\F[]() and \FCodbx_error_type\F[]() to get further details.

ERRORS

-\FCODBX_ERR_BACKEND\F[]
    The native database library couldn't read from the large object

-\FCODBX_ERR_HANDLE\F[]
    \FClo\F[] is NULL or the supplied large object handle is invalid

SEE ALSO
\FCodbx_lo_open\F[](), \FCodbx_lo_close\F[]()