The mi_lo_lolist_create() function

The mi_lo_lolist_create() function converts an array of LO handles into an MI_LO_LIST structure.

Syntax

mi_integer mi_lo_lolist_create(conn, LOhdl_cnt, LO_hdls, LO_list)
   MI_CONNECTION *conn;
   mi_integer LOhdl_cnt;
   MI_LO_HANDLE **LO_hdls;
   MI_LO_LIST **LO_list ;
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_cnt
The number of LO handles in the LO_hdls array.
LO_hdls
A pointer to an array of LO handles that mi_lo_lolist_create() converts.
LO_list
A pointer to the MI_LO_LIST structure that mi_lo_lolist_create() creates.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The mi_lo_lolist_create() function is the constructor function for the MI_LO_LIST structure. It populates an MI_LO_LIST structure with LO handles from the specified LO_hdls array. The MI_LO_LIST structure allows user-defined routines to pass an array of LO handles to and from the database server. The function handles memory allocation for the MI_LO_LIST structure as follows:
  • When the LO_list value points to NULL, this function allocates an MI_LO_LIST structure.
  • When the LO_list value does not point to NULL, the mi_lo_lolist_create() function assumes that LO_list points to memory that has already been allocated by a previous call to mi_lo_lolist_create().

The mi_lo_lolist_create() function allocates a new MI_LO_LIST structure in the current memory duration. The function then initializes the MI_LO_LIST structure with the LO handles, which LO_hdls indicates. It converts the number of LO handles that the LOhdl_cnt argument specifies.

The mi_lo_lolist_create() function is useful in an lohandles() support function of an opaque data type. It converts an array of LO handles to the flat MI_LO_LIST structure that the lohandles() support function returns. The database server automatically manages the reference count of smart large objects when it calls the lohandles() support function at the following times:
  • Assign time (when any assign() support function would execute)
  • Destroy time (when any destroy() support function would execute)
  • Import time (when any import support function would execute)
Server only: The mi_lo_lolist_create() 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

>0
The number of bytes of the MI_LO_LIST structure.
0
The function was not successful.