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 HCL OneDB™ 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.