Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_lo_create() function creates a new smart large object and opens it for access within a DataBlade API module.

MI_LO_FD mi_lo_create(conn, LO_spec, flags, LOhdl_dptr)

MI_CONNECTION *conn;

MI_LO_SPEC *LO_spec;

mi_integer flags;

MI_LO_HANDLE **LOhdl_dptr;

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_spec	is a pointer to the LO-specification structure that contains the storage characteristics to use for the new smart large object.
flags	is an integer that specifies the open mode for the smart large object that LOhdl_dptr references.
LOhdl_dptr	is a doubly indirected pointer to an LO handle that identifies the new smart large object.

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

The mi_lo_create() function is a constructor function for an LO file descriptor. It performs the following steps to create a new smart large object that LOhdl_dptr references:

1. It obtains an LO handle for the new smart large object and assigns a pointer to the handle to the argument that LOhdl_dptr references.

If the *LOhdl_dptr argument is NULL, mi_lo_create() allocates a new LO handle for the new smart large object and assigns a pointer to this handle to *LOhdl_dptr. If *LOhdl_dptr is not NULL, mi_lo_create() assumes that you have already allocated an LO handle and uses the LOhdl_dptr argument to locate the LO handle for the new smart large object.

2. It assigns the storage characteristics from the LO-specification structure, LO_spec, to the new smart large object.

If the LO-specification structure has not been updated with storage characteristics (the associated fields are null), the mi_lo_create() function uses the system-specified storage characteristics.

If the LO-specification structure was updated with storage characteristics, mi_lo_create() uses the storage characteristics that the LO-specification structure defines for the new smart large object.

3. It opens the new smart large object in the open mode that the flags argument specifies.

The flag values for the flags argument indicate the mode of the smart large object after mi_lo_create() successfully completes. For more information on valid open-mode flags, see Open Mode.

4. It returns an LO file descriptor that identifies the new smart large object and is positioned at the start of this smart large object.

When the mi_lo_create() 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().

The mi_lo_create() function allocates a new LO file descriptor in the current memory duration.

Each mi_lo_create() 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_create() function replaces the mi_large_object_create() function, which Informix supports for backward compatibility only. Use mi_lo_create() for all new DataBlade API modules.

Return Values

MI_LO_FD	is the LO file descriptor for the open smart large object that LOhdl_dptr references. The function also initializes the LO handle that LOhdl_dptr references.
MI_ERROR	indicates that the function was not successful.

See the descriptions of the following functions: mi_lo_copy(), mi_lo_expand(), mi_lo_from_file(), mi_lo_spec_init(), mi_lo_colinfo_by_ids(), and mi_lo_colinfo_by_name().

For more information, see Initializing an LO Handle and LO File Descriptor.