The mi_collection_copy() function

The mi_collection_copy() function copies a collection to a new collection variable.

Syntax

MI_COLLECTION *mi_collection_copy(conn, coll_ptr)
   MI_CONNECTION *conn;
   MI_COLLECTION *src_coll;
conn
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
coll_ptr
A pointer to the collection structure for the source collection. This argument is the collection to copy.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The mi_collection_copy() function copies the collection that coll_ptr references to a newly allocated collection structure. This function is a constructor function for the collection structure. It allocates a new collection structure in the current memory duration.

For example, the mi_collection_copy() function creates a copy of the colval collection: 
MI_COLLECTION  *ret_val, *new_retval;
MI_DATUM        colval;

for (i = 0; i < numcols; i++)
   switch( mi_value(row, i, &colval, &collen) )
      {
      case MI_COLLECTION_VALUE:
         ret_val = ( MI_COLLECTION * ) colval;

         if ( (new_retval = 
               mi_collection_copy(conn, ret_val))
               == NULL ) 
            mi_db_error_raise( NULL, MI_FATAL,
               "Fatal Error: Cannot copy collection");
         break;
      } /* end switch */

In this example, the mi_value() function returns a pointer to colval, which is a collection column. However, the memory that is allocated to colval is freed when you close the connection with mi_close(). The copy of colval that the call to the mi_collection_copy() function creates is in the current memory duration. This new collection, which new_retval references, can now be returned from this function.

For a description of collections, see the Informix® DataBlade® API Programmer's Guide.

Return values

An MI_COLLECTION pointer
The address of the newly allocated collection.
NULL
The function was not successful.