The mi_lo_open() function

The mi_lo_open() function opens an existing smart large object for access.

Syntax

MI_LO_FD mi_lo_open(conn, LO_hdl, open_mode)
   MI_CONNECTION *conn;
   MI_LO_HANDLE *LO_hdl;
   mi_integer open_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_hdl
A pointer to the LO handle that identifies the smart large object to open.
open_mode
An integer bit mask that specifies the open mode for the smart large object that LO_hdl references. The bit mask can contain the following open-mode constants:
Table 1. open-mode constants
Category Open-mode constant
Access modes MI_LO_RDONLY = Read-only mode

MI_LO_DIRTY_READ = Dirty-read mode

MI_LO_WRONLY = Write-only mode

MI_LO_APPEND = Write/append mode

MI_LO_RDWR = Read/write mode

MI_LO_TRUNC = Truncate
Access methods MI_LO_RANDOM = Random access

MI_LO_SEQUENTIAL = Sequential access
Buffering modes MI_LO_BUFFER = Buffered access (Buffered I/O)

MI_LO_NOBUFFER = Unbuffered access (Light-weight I/O)
Locking modes MI_LO_LOCKALL = Lock-all locks

MI_LO_LOCKRANGE = Byte-range locks
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_open() function opens the existing smart large object that LO_hdl references. To access the data of a smart large object, a DataBlade® API module must first open the smart large object. The mi_lo_open() function performs the following steps:
  1. It opens the smart large object that LO_hdl references in the open mode that the open_mode flag indicates.
    • If the open_mode flag is zero, mi_lo_open() uses the default open mode, which you can set in the LO-specification structure with the mi_lo_specset_def_open_flags() function.
    • A non-zero open_mode flag specifies the open-mode information with a valid combination of open-mode constants.
  2. It sets the LO seek position of the smart large object to byte zero.
  3. It obtains a lock on the smart-large-object data based on the lock mode in the open_mode argument.
  4. It returns an LO file descriptor that identifies the smart large object.

    When the mi_lo_open() function is successful, it returns a valid LO file descriptor. The mi_lo_open() function is a constructor function for an LO file descriptor. You can then use this file descriptor to identify which smart large object to access in subsequent function calls such as mi_lo_read() and mi_lo_write(). However, this LO file descriptor is only valid within the current session.

Server only: The mi_lo_open() function allocates a new LO file descriptor in the current memory duration.
Important: The database server does not check access permissions on the smart large object that the LO handle identifies. Your DataBlade® API module must ensure that the end user or another application is trusted.

Each mi_lo_open() call is implicitly associated with the current session. When this session ends, the database server deallocates any smart large objects that are not referenced by any columns (those with a reference count of zero.

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

An MI_LO_FD value
The LO file descriptor for the open smart large object that LO_hdl references.
MI_ERROR
The function was not successful.