Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

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

MI_LO_FD mi_lo_open(conn, LO_hdl, flags)

MI_CONNECTION *conn;

MI_LO_HANDLE *LO_hdl;

mi_integer flags;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
LO_hdl	is a pointer to the LO handle that identifies the smart large object to open.
flags	is an integer that is a bit mask that specifies the open mode for the smart large object that LO_hdl references.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_lo_open() function is a constructor function for an LO file descriptor. 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 opens an existing smart large object. The mi_lo_open() function performs the following steps to open the existing smart large object that LO_hdl references:

1. It opens the new smart large object that LO_hdl references in the specified open mode.

By default, mi_lo_open() uses the default open mode, which you can set in the LO-specification structure with the mi_lo_specset_def_open() function.

If you do not set a default open mode or if you want to override it, you can specify the flags argument to mi_lo_open(). The flag values for the flags argument indicate the mode of the smart large object after mi_lo_open() successfully completes. For more information on valid open-mode flags, see Open Mode.

2. It sets the LO seek position of the smart large object to byte zero (0).
3. It obtains a lock on the smart-large-object data based on the open mode in the flags argument.

The lock that mi_lo_open() obtains is released when the current transaction terminates.

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. 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 database session.

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 (0)).

Tip: The mi_lo_open() function replaces the mi_large_object_open() function, which Informix supports for backward compatibility only. Use mi_lo_open() for all new DataBlade API modules.

Return Values

MI_LO_FD	is the LO file descriptor for the open smart large object that LO_hdl references.
MI_ERROR	indicates that the function was not successful.

See the descriptions of the following functions: mi_lo_close, mi_lo_copy(), mi_lo_create(), mi_lo_expand(), mi_lo_read(), mi_lo_readwithseek(), mi_lo_specget_def_open(), mi_lo_specset_def_open(), mi_lo_tell(), mi_lo_write(), and mi_lo_writewithseek().

For more information, see Opening a Smart Large Object and Smart-Large-Object Locks.