NAME

       odbx_lo_open - Opens a large object in the database

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_lo_open (odbx_result_t* result, odbx_lo_t** lo, const char* value);

DESCRIPTION

       Some  database  management  systems  store large amount of data in separate regions of the
       database and the content is only referenced by identifiers in the tables. The  data  types
       used  for this are called Binary Large OBject (BLOB) and Character Large OBject (CLOB) and
       can be found in e.g. the  Firebird  and  Oracle  database  servers.  The  OpenDBX  library
       provides  a  large  object  interface  to  access,  read  and  write their content via the
       "odbx_lo_*()" functions. To find out if large amount of data can be accessed  directly  or
       if  the  large  object  interface have to be used, odbx_capabilities() provides the answer
       when feed with the ODBX_CAP_LO

       The result parameter has to be the result object created and returned by odbx_result(). It
       becomes  invalid  after  it  was  supplied  to odbx_result_finish() and this function will
       return an error in that case. The second parameter, the  pointer  to  a  odbx_lo_t*,  will
       contain the newly created large object handle if odbx_lo_open() succeeds. The lo handle is
       necessary for all other functions of the large  object  interface  so  they  are  able  to
       perform  their operations on the referenced content. The last parameter must be the return
       value of odbx_field_value() but you have to check for NULL values before feeding the value
       to odbx_lo_open(). Otherwise, an error is returned.

RETURN VALUE

       odbx_lo_open() returns ODBX_ERR_SUCCESS, or an error code whose value is less than zero 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 odbx_error() and odbx_error_type() to get
       further details.

ERRORS

       -ODBX_ERR_BACKEND
              The native database library couldn't open the large object

       -ODBX_ERR_NOMEM
              Allocating additionally required memory failed

SEE ALSO

       odbx_capabilities(), odbx_field_value(), odbx_lo_close(), odbx_lo_read(), odbx_lo_write(),
       odbx_result()

                                         17 October 2021                          odbx_lo_open(3)