Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_lo_copy() function creates a copy of a smart large object and opens the copy.

MI_LO_FD mi_lo_copy(conn, src_LOhdl, LO_spec, flags, target_LOhdl_dptr)

MI_CONNECTION *conn;

MI_LO_HANDLE *src_LOhdl;

MI_LO_SPEC *LO_spec;

mi_integer flags;

MI_LO_HANDLE **target_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.
src_LOhdl	is a pointer to the LO handle for the existing smart large object that is to be copied.
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 mode in which to open the new smart large object that target_LOhdl_dptr references.
target_LOhdl_dptr	is a doubly indirected pointer to the target LO handle that identifies the new smart large object where mi_lo_copy() copies the data in the smart large object that src_LOhdl references.

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

The mi_lo_copy() function is a constructor function for an LO file descriptor. It performs the following steps to create a new smart large object whose data is copied from the smart large object that src_LOhdl references:

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

If the *target_LOhdl_dptr value points to NULL, mi_lo_copy() allocates a new LO handle for the new smart large object and assigns a pointer to this handle to *target_LOhdl_dptr. If *target_LOhdl_dptr does not point to NULL, mi_lo_copy() assumes that you have already allocated an LO handle and uses the target_LOhdl_dptr argument as a pointer to an existing LO handle.

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_copy() function uses the system-specified storage characteristics.

If the LO-specification structure was updated with storage characteristics, mi_lo_copy() 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_copy() successfully completes. For more information on valid open-mode flags, see Open Mode.

4. It copies the contents of the data in the smart large object that src_LOhdl references into the new smart large object that target_LOhdl_dptr references.