Collection Binary Representation

Home | Previous Page | Next Page Data Manipulation > Using Complex Data Types > Collections >

Collection Binary Representation

The database server supports the following kinds of collections.

Collection Data Type: Description
LIST: An ordered group of elements that can contain duplicate elements
MULTISET: An unordered group of elements that can contain duplicate elements
SET: An unordered group of elements that cannot contain duplicate elements

All collection data types use the same internal format to store their values. For more information on collection data types, see the IBM Informix: Guide to SQL Reference.

Tip:

The internal format of a collection data type is often referred to as its binary representation.

The DataBlade API supports the following SQL collection data types and data type structures:

A collection structure (MI_COLLECTION) holds the binary representation of the collection.
A collection descriptor (MI_COLL_DESC) provides information about the collection.

Using a Collection Structure

A collection structure, MI_COLLECTION, is a DataBlade API structure that holds the collection (LIST, MULTISET, or SET) and its elements. The following table summarizes the memory operations for a collection structure.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_collection_copy( ), mi_collection_create( ), mi_streamread_collection( )
Current memory duration	Destructor	mi_collection_free( )

The following DataBlade API functions return an existing collection structure.

DataBlade API Function	Description
mi_value( ), mi_value_by_name( )	Returns a collection structure as a column value when the function returns an MI_COLLECTION_VALUE value status

Using a Collection Descriptor

A collection descriptor, MI_COLL_DESC, is a DataBlade API structure that contains a collection cursor to access elements of a collection. The following table summarizes the memory operations for a collection descriptor.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_collection_open( ), mi_collection_open_with_options( )
Current memory duration	Destructor	mi_collection_close( )

Important:

To a DataBlade API module, the collection descriptor (MI_COLL_DESC) is an opaque C data structure. Do not access its internal fields directly. The internal structure of a collection descriptor may change in future releases. Therefore, to create portable code, always use the functions that access collection elements.