The mi_collection_open_with_options() function
The mi_collection_open_with_options() function opens a collection in a specified open mode.
Syntax
MI_COLL_DESC *mi_collection_open(conn, coll_ptr, control)
MI_CONNECTION *conn;
MI_COLLECTION *coll_ptr;
mi_integer control;- 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 to open.
- control
- A bit-mask integer value that specifies the type of collection
cursor to create and open. The following bit-mask flags are valid:
- MI_COLL_READONLY
- Cursor is read-only.
- MI_COLL_NOSCROLL
- Cursor A sequential cursor (not a scroll cursor).
Valid in client LIBMI application? Valid in user-defined routine? Yes Yes
Usage
The mi_collection_open_with_options() function is a constructor function for the collection descriptor. The function opens the collection that coll_ptr references and returns a collection descriptor for the open collection. Other DataBlade® API collection functions use this collection descriptor to access the elements of a collection.
For a description of collections, see the Informix® DataBlade® API Programmer's Guide.
Server only: The mi_collection_open_with_options() function
allocates a new collection descriptor in the current memory duration.
This
function creates a collection cursor to hold the collection elements.
By default, this cursor is an update scroll cursor. If this type of
cursor is not adequate for your DataBlade®
API module,
you can create a collection cursor with characteristics specified
by a bit mask in the control argument.
- Collection cursor type
- Control-flag value
- Update scroll cursor
- None (default)
- Read-only scroll cursor
- MI_COLL_READONLY
- Update sequential cursor
- MI_COLL_NOSCROLL
- Read-only sequential cursor
- MI_COLL_READONLY + MI_COLL_NOSCROLL
This function is useful for accessing collection subqueries.
Return values
- An MI_COLL_DESC pointer
- The address of the collection descriptor for the opened collection.
- NULL
- The function was not successful.