Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

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

MI_COLLECTION *mi_collection_copy(conn, src_coll)

MI_CONNECTION *conn;

MI_COLLECTION *src_coll;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() established.
src_coll	is 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

The mi_collection_copy() function copies the collection that src_coll 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.

See the descriptions of the following functions: mi_collection_close(), mi_collection_create(), mi_collection_delete(), mi_collection_fetch(), mi_collection_free(), mi_collection_insert(), mi_collection_open(), and mi_collection_update().

For a description of collections, see Collections.