The mi_lo_lock() function

The mi_lo_lock() function obtains a byte-range lock on the specified number of bytes in a smart large object.

Syntax

mi_integer mi_lo_lock(conn, LO_fd, offset, whence, nbytes, lock_mode)
   MI_CONNECTION *conn;
   MI_LO_FD LO_fd;
   mi_int8 *offset;
   mi_integer whence;
   mi_int8 *nbytes;
   mi_integer lock_mode;
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
The LO file descriptor of the smart large object to lock.
offset
A pointer to the eight-byte integer (mi_int8) offset from the starting LO seek position that whence specifies.
whence
An integer value that identifies the starting LO seek position.
nbytes
A pointer to the eight-byte integer (mi_int8) that specifies the number of bytes to lock. This value cannot exceed 2 GB.
lock_mode
An integer constant that indicates the lock mode to use. Valid constant values are:
MI_LO_SHARED_MODE
Lock mode is shared mode.
MI_LO_EXCLUSIVE_MODE
Lock mode is exclusive mode.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The mi_lo_lock() function requests a byte-range lock of the lock_mode type on the open smart large object that LO_fd indicates. This lock request applies to nbytes number of bytes beginning at the LO seek location that the whence and offset arguments specify.

By default, the database server locks the entire smart large object when you request a read or write operation. With the mi_lo_lock() function, you can request a byte-range lock, which allows transactions to lock only the required ranges of bytes in a smart large object. However, the smart large object on which you request the byte-range lock must have the byte-range locking feature enabled with the LO_LOCKRANGE storage-characteristic constant.

For more information about locks for smart large objects or about how to use byte-range locks, see the Informix® DataBlade® API Programmer's Guide.

Server only: The mi_lo_lock() 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

MI_OK
The function was successful; the requested lock was successfully obtained.
MI_ERROR
The function was not successful; the requested lock cannot be obtained or the smart large object has not been opened for byte-range locking.