The mi_lo_write() function

The mi_lo_write() function writes a specified number of bytes to an open smart large object.

Syntax

mi_integer mi_lo_write(conn, LO_fd, buf, nbytes)
   MI_CONNECTION *conn;
   MI_LO_FD LO_fd;
   const char *buf;
   mi_integer nbytes;
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_fd
An LO file descriptor for the smart large object to which to write. It is obtained by a previous call to the mi_lo_open() function.
buf
A pointer to a user-allocated character buffer of at least nbytes bytes that contains the data to be written to the smart large object.
nbytes
The maximum number of bytes to write to the smart large object. This value cannot exceed 2 GB.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_write() function writes nbytes of data to the smart large object that the LO_fd file descriptor identifies. The write begins at the current LO seek position for LO_fd. You can use the mi_lo_tell() function to obtain the current LO seek position.

The function obtains the data from the user-allocated buffer that buf references. The buf buffer must be less than 2 GB in size.

If the database server writes less than nbytes of data to the smart large object, the mi_lo_write() function returns the number of bytes that it wrote and raises an exception. This condition can occur when the sbspace runs out of space.

To perform a seek operation before a write operation, use the mi_lo_writewithseek() function.

Server only: The mi_lo_write() 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 that the function has written from the buf character buffer, the open smart large object.
MI_ERROR
The function was not successful.