Initializing an LO Handle and an LO File Descriptor

Once you have an LO-specification structure that describes the storage characteristics for the new smart large object, you can create the smart large object with one of the smart-large-object creation functions: mi_lo_copy( ), mi_lo_create( ), mi_lo_expand( ), or mi_lo_from_file( ). These smart-large-object creation functions perform the following tasks to create a new smart large object:

1. Initialize the LO handle for the new smart large object

   You provide a pointer to an LO handle as an argument to these functions. The creation functions initialize the LO handle with information about the location of the new smart large object.

2. Store the storage characteristics in a user-supplied LO-specification structure for the new smart large object in the metadata area of the sbspace

   You provide a pointer to an LO-specification structure as an argument to these functions. For more information, see Obtaining the LO-Specification Structure.

3. Open the new smart large object in the specified access mode

   You provide the open mode as an argument to the mi_lo_create( ), mi_lo_copy( ), or mi_lo_expand( ) function. The mi_lo_from_file( ) function opens a smart large object in read/write mode. For more information, see Opening a Smart Large Object.

4. Write any associated data to the new smart large object

   The mi_lo_copy( ), mi_lo_expand( ), and mi_lo_from_file( ) function specifies data to write to the sbspace of the new smart large object.

5. Return an LO file descriptor that identifies the open smart large object

   The LO file descriptor is needed for most subsequent operations on the smart large object. However, this LO file descriptor is only valid within the current database connection.

These smart-large-object creation functions initialize the following data type structures for a smart large object:

• An LO handle, which identifies the location of the smart large object and can be stored in a CLOB, BLOB, or opaque-type column
• An LO file descriptor, which identifies the open smart large object

Obtaining an LO Handle

A DataBlade API module can obtain an LO handle with any of the following methods:

• Any of the smart-large-object creation functions can allocate an LO handle for a new smart large object.
• A DataBlade API module can explicitly allocate an LO handle.
• A SELECT statement can return an LO handle from a CLOB or BLOB column in the database.

For more information, see Selecting the LO Handle.

Implicitly Allocating an LO Handle

Any of the smart-large-object creation functions (Table 29) can allocate memory for an LO handle when you specify a NULL-valued pointer for the last argument. For example, the following code fragment declares a pointer to an LO handle named LO_hdl, initializes it to NULL, and then calls the mi_lo_create( ) function to allocate memory for this LO handle:

MI_CONNECTION *conn;
MI_LO_SPEC *LO_spec;
MI_LO_HANDLE *LO_hdl = NULL; /* request allocation */
MI_LO_FD LO_fd;
mi_integer flags;
...
LO_fd = mi_lo_create(conn, &LO_spec, flags, &LO_hdl);

After the execution of mi_lo_create( ), the LO_hdl variable is a pointer to the new LO handle, which identifies the location of the new smart large object.

If you provide an LO-handle pointer that does not point to NULL, the smart-large-object creation function assumes that memory has already been allocated for the LO handle and it uses the LO handle that you provide.

Explicitly Allocating an LO Handle

You can explicitly allocate an LO handle in either of the following ways:

• Dynamically, with one of the DataBlade API memory-management functions such as mi_alloc( ):

  MI_LO_HANDLE *LO_hdl = mi_alloc(sizeof(MI_LO_HANDLE));

• On the stack, with a direct declaration:

  MI_LO_HANDLE my_LOhndl;
  MI_LO_HANDLE *LO_hdl2, &my_LOhndl;

However, this LO handle is still an opaque C data structure; that is, it is declared as a flat array of undifferentiated bytes and its fields are not available to the DataBlade API module.

Obtaining an LO File Descriptor

The smart-large-object creation functions (Table 29) return an LO file descriptor for a smart large object. The LO file descriptor is needed for most subsequent operations on the smart large object. However, this LO file descriptor is only valid within the current database connection.

The following code fragment uses the mi_lo_create( ) function to generate an LO file descriptor for a new smart large object:

MI_LO_FD LO_fd;
MI_LO_HANDLE *LO_hdl;
MI_LO_SPEC *LO_spec;
MI_CONNECTION *conn;
...
LO_fd = mi_lo_create(conn, LO_spec, MI_LO_RDONLY, &LO_hdl);