Home
Extending HCL OneDB™Beyond standard relational database objects, HCL OneDB™ can be extended to handle specialized data types, access methods, routines, and other objects. HCL OneDB™ includes many built-in extensions that are fully integrated in the database server. HCL OneDB™ also provides DataBlade® modules, which are packages of extended database objects for a particular purpose and that are installed separately from the database server. Alternatively, you can create your own user-defined objects for HCL OneDB™.
Creating extensionsYou can create user-defined data types, routines, access methods, and other database objects to suit your needs. You can use application programming interfaces to write user-defined routines and applications that access data in HCL OneDB™ databases.
DataBlade® API Function ReferenceThe HCL OneDB™ DataBlade® API Function Reference describes the DataBlade® API functions and the subset of functions that the DataBlade® API supports.
Function descriptionsThis section gives comprehensive reference information about the functions that are valid within DataBlade® API modules. It lists the function descriptions in alphabetical order, with syntax, usage information, and return values for the functions.
The mi_lo_create() functionThe mi_lo_create() function creates a new smart large object and opens it for access within a DataBlade® API module.

The mi_lo_create() function

The mi_lo_create() function creates a new smart large object and opens it for access within a DataBlade® API module.

Syntax

MI_LO_FD mi_lo_create(conn, LO_spec, open_mode, LOhdl_dptr)
   MI_CONNECTION *conn;
   MI_LO_SPEC *LO_spec;
   mi_integer open_mode;
   MI_LO_HANDLE **LOhdl_dptr;

conn

This value is one of the following connection values:

A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

A NULL-valued pointer (database server only)

LO_spec

A pointer to the LO-specification structure that contains the storage characteristics to use for the new smart large object.

open_mode

An integer bitmask that specifies the open mode for the smart large object that LOhdl_dptr references.

LOhdl_dptr

A doubly indirected pointer to an LO handle that identifies the new smart large object.


Valid in client LIBMI application?	Valid in user-defined routine?
Yes	Yes

Usage

The mi_lo_create() function performs the following steps to create a new smart large object that LOhdl_dptr references:

It obtains an LO handle for the new smart large object and assigns a pointer to the handle to the argument that LOhdl_dptr references.
If the LOhdl_dptr argument is NULL, mi_lo_create() allocates a new LO handle for the new smart large object and assigns a pointer to this handle to LOhdl_dptr. If LOhdl_dptr is not NULL, mi_lo_create() assumes that you have already allocated an LO handle and uses the LOhdl_dptr argument to locate the LO handle for the new smart large object.
It assigns the storage characteristics from the LO-specification structure, LO_spec, to the new smart large object.
If the LO-specification structure has not been updated with storage characteristics (the associated fields are null), the mi_lo_create() function uses the system-specified storage characteristics.
If the LO-specification structure was updated with storage characteristics, mi_lo_create() uses the storage characteristics that the LO-specification structure defines for the new smart large object.
It opens the new smart large object in the open mode that the open_mode argument specifies.
The bitmask value for the open_mode argument indicates the open mode of the smart large object after mi_lo_create() successfully completes. For more information about valid open-mode flags, see the HCL OneDB™ DataBlade API Programmer's Guide.
It returns an LO file descriptor that identifies the new smart large object and is positioned at the start of this smart large object.
When the mi_lo_create() function is successful, it returns a valid LO file descriptor. You can then use this file descriptor to identify which smart large object to access in subsequent function calls, such as mi_lo_read() and mi_lo_write().

The mi_lo_create() function is a constructor function for both an LO file descriptor and an LO handle.

Server only: If the mi_lo_create() function allocates an LO handle, it allocates this LO handle in the current memory duration. The mi_lo_create() function does not allocate memory for the LO file descriptor. Your UDR can assign this LO file descriptor to user memory with a desired memory duration.

Each mi_lo_create() call is implicitly associated with the current session. When this session ends, the database server deallocates any smart large objects that mi_lo_create() has created if its LO handle has not been stored in a column (its reference count is zero) and no open LO file descriptors exist for the smart large object.

Server only: The mi_lo_create() function does not need a connection descriptor to execute. If your UDR does not need a valid connection for other operations, you can specify a NULL-valued pointer for the conn parameter to establish a NULL connection. For information about the advantages of a NULL connection, see the HCL OneDB DataBlade API Programmer's Guide.

Return values

An MI_LO_FD value: The LO file descriptor for the open smart large object that LOhdl_dptr references. The function also initializes the LO handle that LOhdl_dptr references.
MI_ERROR: The function was not successful.