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 HCL OneDB™ 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.