MI_LO_FD mi_lo_expand(conn, LOhdl_dptr, multirep_ptr, multirep_len,
   open_mode, LO_spec)
   MI_CONNECTION *conn;
   MI_LO_HANDLE **LOhdl_dptr;
   MI_MULTIREP_DATA *multirep_ptr;
   mi_integer multirep_len;
   mi_integer open_mode;
   MI_LO_SPEC *LO_spec;

conn

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)

LOhdl_dptr

is a doubly indirected pointer to an LO handle that identifies the new smart large object into which mi_lo_expand( ) copies the multirepresentational data.

multirep_ptr

is a pointer to a buffer that contains the multirepresentational data to store in the new smart large object.

multirep_len

is an integer that specifies the size of the multirep_ptr data, in bytes.

open_mode

is an integer bitmask that specifies the open mode for the smart large object that LOhdl_dptr references.

LO_spec

is a pointer to the LO-specification structure that contains the storage characteristics to use for the new smart large object.

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

The mi_lo_expand( ) function performs the following steps to create a new smart large object that LOhdl_dptr references and to copy multirepresentational data into this new smart large object:

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_expand( ) 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_expand( ) assumes that you have already allocated an LO handle and uses the LOhdl_ptr 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_expand( ) function uses the system-specified storage characteristics.

   If the LO-specification structure was updated with storage characteristics, mi_lo_expand( ) 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 open_mode argument specifies.

   The bitmask value for the open_mode argument indicates the open mode of the smart large object after mi_lo_expand( ) successfully completes. For more information on valid open-mode flags, see the IBM Informix: DataBlade API Programmer's Guide.

4. It copies the contents of the multirepresentational data in the multirep_ptr buffer into the new smart large object that LOhdl_dptr references.

   The mi_lo_expand( ) function copies multirep_len bytes of the multirepresentational data to the sbspace of the new smart large object.

5. 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_expand( ) 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_expand( ) function is a constructor function for both an LO file descriptor and an LO handle.

Each mi_lo_expand( ) call is implicitly associated with the current session. When this session ends, the database server deallocates any smart large objects that mi_lo_expand( ) has created if its LO handle has not been stored in a column (its reference count is zero) and no open LO file descriptors exist for the smart large object.

An MI_LO_FD value

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 also the descriptions of mi_lo_copy( ), mi_lo_create( ), mi_lo_from_file( ), mi_lo_spec_init( ), mi_lo_open( ), and mi_set_large( ).