The mi_lo_spec_init() function

The mi_lo_spec_init() function allocates and initializes the default system storage characteristics that are used to create a smart large object.

Syntax

mi_integer mi_lo_spec_init(conn, LOspec_dptr)
   MI_CONNECTION *conn;
   MI_LO_SPEC **LOspec_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)

LOspec_dptr
A doubly indirected pointer to an LO-specification structure for a smart large object.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_spec_init() function is a constructor for the LO-specification structure. It performs the following steps to create an LO-specification structure:
  1. It handles memory allocation for an LO-specification structure.

    When the LOspec_dptr value (a single indirect pointer to an LO-specification structure) is NULL, this function allocates an LO- specification structure. Before you use an LO-specification structure, set LOspec_dptr to NULL so that mi_lo_spec_init() allocates space for the LO-specification structure. When LOspec_dptr does not point to NULL, the mi_lo_spec_init() function assumes that LOspec_dptr points to an LO-specification structure that has already been allocated by a previous call to mi_lo_spec_init().

  2. It initializes the fields in the LO-specification structure, which LOspec_dptr references, to the appropriate null values (zero or a NULL-valued pointer).

    When the smart-large-object optimizer receives this initialized LO-specification structure, it obtains system-specified storage characteristics for the new smart large object.

Server only: The mi_lo_spec_init() function allocates a new LO-specification structure in the current memory duration.

The mi_lo_spec_init() 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.

Important: Before you use an LO-specification structure in a DataBlade API module, you must either allocate a new one with the mi_lo_spec_init() function or obtain one from an existing smart large object with the mi_lo_stat_cspec() function. You can use the mi_lo_colinfo_by_ids() or mi_lo_colinfo_by_name() function to obtain storage characteristics that are associated with a particular column.

Do not use system memory-allocation calls (such as malloc() or mi_alloc()) to perform memory management for LO-specification structures. Use the mi_lo_spec_init() function to create a new LO-specification structure and the mi_lo_spec_free() function to free an LO-specification structure.

Return values

MI_OK
The function was successful.
MI_ERROR
The function was not successful.