The mi_lo_to_buffer() function

The mi_lo_to_buffer() function copies a specified number of bytes from a smart large object to a user-defined buffer.

Syntax

mi_integer mi_lo_to_buffer(conn, LO_hdl, size, buf_ptr)
   MI_CONNECTION *conn;
   MI_LO_HANDLE *LO_hdl;
   mi_integer size;
   char **buf_ptr;
conn
This value is one of the following connection values:

A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

A NULL-valued pointer (database server only)

LO_hdl
The LO handle for the smart large object from which you want to copy the data.
size
is an integer number of bytes to copy from the smart large object.
buf_ptr
A doubly indirected pointer to a user-defined buffer to which you want to copy the data.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_to_buffer() function copies up to size bytes from the smart large object that the LO_hdl LO handle references. The read operation from the smart large object starts at a zero-byte offset. This function allows you to read data from a smart large object without opening the smart large object.

If the smart large object is smaller than the size value, mi_lo_to_buffer() copies only the number of bytes in the smart large object. If the smart large object contains more than size bytes, the mi_lo_to_buffer() function copies only size bytes to the user-defined buffer.

When buf_ptr points to NULL, mi_lo_to_buffer() allocates the memory for the buffer. Otherwise, the function assumes that you have allocated memory that buf_ptr references.

Server only: The mi_lo_to_buffer() function does not need a connection descriptor to execute. If your UDR does not need a valid connection for other operations, you can specify a NULL-valued pointer for the conn parameter to establish a NULL connection. For information about the advantages of a NULL connection, see the Informix® DataBlade® API Programmer's Guide.

Return values

>=0
The number of bytes copied from the smart large object to the user-defined buffer that buf_ptr references.
MI_ERROR
The function was not successful.