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_dalloc() functionThe mi_dalloc() function allocates the specified amount of memory for the specified memory duration and returns a pointer to the allocated block.

The mi_dalloc() function

The mi_dalloc() function allocates the specified amount of memory for the specified memory duration and returns a pointer to the allocated block.

Syntax

void *mi_dalloc (size, duration)
   mi_integer size;
   MI_MEMORY_DURATION duration;

size

The number of bytes to allocate.

duration

A value that specifies the memory duration of the user memory to allocate. Valid values for duration follow:

PER_ROUTINE: For the duration of one iteration of the UDR
PER_COMMAND: For the duration of the execution of the current subquery
PER_STATEMENT (Deprecated): For the duration of the current SQL statement
PER_STMT_EXEC: For the duration of the execution of the current SQL statement
PER_STMT_PREP: For the duration of the current prepared SQL statement
PER_TRANSACTION (Advanced): For the duration of one transaction
PER_SESSION (Advanced): For the duration of the current client session
PER_SYSTEM (Advanced): For the duration of the database server execution


Valid in client LIBMI application?	Valid in user-defined routine?
Yes (however, the application ignores memory duration)	Yes

Usage

The mi_dalloc() function allocates size number of bytes of shared memory with duration memory duration for a DataBlade® API module. The mi_dalloc() function is a constructor function for user memory. This function behaves exactly like mi_alloc() except that mi_dalloc() enables you to specify the memory duration explicitly at allocation time.

Server only:

For most memory allocations in a C UDR, the duration argument must be one of the following public memory-duration constants:

PER_ROUTINE (or PER_FUNCTION)
If you specify PER_ROUTINE, the database server frees the allocated memory when the UDR returns.
PER_COMMAND
If you specify PER_COMMAND, the database server frees memory when the execution of a subquery is complete.
PER_STMT_EXEC
If you specify PER_STMT_EXEC, the database server frees memory when the execution of an SQL statement is complete.
PER_STMT_PREP
If you specify PER_STMT_PREP, the database server frees memory when a prepared SQL statement terminates.

Important: Use an advanced memory duration in your C UDR only if a regular memory duration cannot safely perform the task you need done. These advanced memory durations have long duration times and can increase the possibility of memory leakage.

In C UDRs, the database server automatically frees memory allocated with mi_dalloc() when an exception is raised.

Important: In C UDRs, use DataBlade API memory-management functions to allocate memory. Use of a DataBlade API memory-management function guarantees that the database server can automatically free the memory, especially in case of a return value or exception, where the routine would not be able to free the memory.

A UDR can use mi_free() to free memory allocated by mi_dalloc() explicitly when that memory is no longer needed.

Client only: In client LIBMI applications, mi_dalloc() works exactly like malloc(): storage is allocated on the heap of the client process. The database server, however, does not automatically free this memory. Therefore, the client LIBMI application must use the mi_free() function to free explicitly all allocations that mi_dalloc() makes.

Client LIBMI applications ignore memory duration.

Within a callback function, a call to mi_dalloc() that requests a duration of PER_COMMAND returns NULL. Therefore, a callback function must call mi_dalloc() with a duration of PER_ROUTINE.

The mi_dalloc() function returns a pointer to the newly allocated memory. Cast this pointer to match the structure of the user-defined buffer or structure that you allocate.

For more information about memory allocation and memory duration, see the HCL OneDB™ DataBlade API Programmer's Guide.

Return values

A void pointer: A pointer to the newly allocated memory. Cast this pointer to match the user-defined buffer or structure for which the memory was allocated.
NULL: The function was unable to allocate the memory.

The mi_dalloc() function does not throw an MI_Exception event when it encounters a runtime error. Therefore, the function does not cause callbacks to be invoked.