The mi_lo_readwithseek() function

The mi_lo_readwithseek() function performs a seek operation and then reads a specified number of bytes of data from an open smart large object.

Syntax

mi_integer mi_lo_readwithseek(conn, LO_fd, buf, nbytes, offset, whence)
   MI_CONNECTION *conn;
   MI_LO_FD LO_fd;
   char *buf;
   mi_integer nbytes;
   mi_int8 *offset;
   mi_integer whence;
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 from which to read.
buf
A pointer to a user-allocated character buffer that contains the data that mi_lo_readwithseek() reads from the smart large object.
nbytes
The maximum number of bytes to read from the buf character buffer. This value cannot exceed 2 GB.
offset
A pointer to the eight-byte integer (mi_int8) offset from the starting LO seek position.
whence
An integer value that identifies the starting LO seek position.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_readwithseek() function reads nbytes of data from the open smart large object that the LO_fd file descriptor identifies. The read begins at the LO seek position of LO_fd that the offset and whence arguments indicate, as follows:
  • The whence argument identifies the position from which to start the seek operation.
    Valid values include the following whence constants.
    Whence constant
    Starting LO seek position
    MI_LO_SEEK_SET
    The start of the smart large object
    MI_LO_SEEK_CUR
    The current LO seek position in the smart large object
    MI_LO_SEEK_END
    The end of the smart large object
    • The offset argument identifies the offset, in bytes, relative to the starting seek position (which the whence argument specifies) at which to begin the read operation.

      This offset value can be negative for all values of whence. For more information about how to access eight-bit (INT8) integers, see the HCL OneDB™ DataBlade® API Programmer's Guide.

The function reads this data into the user-allocated buffer that buf references. The buf buffer must be less than 2 GB in size. To read smart large objects that are larger than 2 GB, read them in 2 GB chunks.

Server only: The mi_lo_readwithseek() 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 HCL OneDB DataBlade API Programmer's Guide.

Return values

>=0
The number of bytes that the function has read from the open smart large object to the buf character buffer.
MI_ERROR
The function was not successful.