Obtaining the LO-Specification Structure

Before you create a new smart large object, obtain a valid LO-specification structure to hold its storage characteristics. You can obtain an LO-specification structure in either of the following ways:

• Create a new LO-specification structure to hold the storage characteristics of a new smart large object with the mi_lo_spec_init( ) function.
• Obtain an LO-specification structure that holds the storage characteristics of an existing smart large object with the mi_lo_stat_cspec( ) function.

Specifying New Storage Characteristics

The mi_lo_spec_init( ) function is the constructor for the LO-specification structure. This function performs the following tasks to create a new LO-specification structure:

1. It allocates a new LO-specification structure when you provide a NULL-valued pointer as an argument.
2. It initializes all fields of the LO-specification structure (disk-storage information and attributes flag) to the appropriate null values.

Allocating Memory for an LO-Specification Structure

When you pass a NULL-valued pointer as the second argument of the mi_lo_spec_init( ) function, this function allocates an LO-specification structure.

The following code fragment declares a pointer named myspec and initializes this pointer to NULL:

MI_LO_SPEC *myspec;
MI_CONNECTION *conn;
...
/* Allocate a new LO-specification structure */
myspec = NULL;
if ( mi_lo_spec_init(conn, &myspec) != MI_OK )
   handle_error( );
/* Perform tasks with LO-specification structure */
...

/* Once finished with LO-specification structure, free it */
if ( mi_lo_spec_free(conn, myspec)!= MI_OK )
   handle_error( );

After the execution of mi_lo_spec_init( ), the myspec variable points to the newly allocated LO-specification structure. For more information on how to use an LO-specification structure to create a new smart large object, see Choosing Storage Characteristics.

If you provide a second argument that does not point to NULL, the mi_lo_spec_init( ) function assumes that this pointer references an existing LO-specification structure that a previous call to mi_lo_spec_init( ) has allocated. An LO-specification pointer that is not NULL allows a DataBlade API module to reuse an LO-specification structure. The following code fragment reuses the LO-specification structure that the LO_spec pointer references when the first_time flag is false:

MI_CONNECTION *conn;
MI_LO_SPEC *LO_spec = NULL;
mi_integer first_time;
...
if ( first_time )
   {
   ...
   LO_spec = NULL; /* tell interface to allocate memory */
   first_time = 0; /* set "first_time" flag to false */
   ...
   }
if ( mi_lo_spec_init(conn, &LO_spec) != MI_OK )
   {
   /* error */
   }

Once you have a valid LO-specification structure, you can use the accessor functions to obtain the storage characteristics from this LO-specification structure. For more information, see Defining User-Specified Storage Characteristics. For the syntax of mi_lo_spec_init( ), see the IBM Informix: DataBlade API Function Reference.

Initializing an LO-Specification Structure

The mi_lo_spec_init( ) function initializes the LO-specification structure with values that obtain the system-specified storage characteristics. The system-specified storage characteristics are the defaults that the database server uses. They are the storage characteristics at the bottom of the storage-characteristics hierarchy.

After this initialization, you can change the values in the LO-specification structure:

• The new smart large object inherits column-level storage characteristics of a CLOB or BLOB column.
• You provide user-specified storage characteristics for the new smart large object.

For more information on storage characteristics and the storage-characteristics hierarchy, see Choosing Storage Characteristics.

Copying Storage Characteristics from an Existing Smart Large Object

The mi_lo_stat_cspec( ) function copies the storage characteristics from an existing smart large object to an LO-specification structure. This function performs the following tasks:

1. It allocates a new LO-specification structure to hold the storage characteristics.
2. It initializes all fields of this LO-specification structure (disk-storage information and attributes flag) to the values of the storage characteristics of the smart large object whose status information is in the LO-status structure that you pass as an argument.
3. It returns the address of the newly allocated LO-specification structure.

The LO-status structure holds status information for an existing smart large object. You initialize an LO-status structure with the mi_lo_stat( ) function. For more information on an LO-status structure, see Obtaining Status Information.

The following code fragment assumes that the old_LOfd variable has already been initialized as the LO file descriptor of an existing smart large object. This code fragment uses the storage characteristics of the existing smart large object (which the mi_lo_stat( ) function puts into the LO-specification structure that LO_spec specifies) as the storage characteristics for the new smart large object (which the mi_lo_create( ) function creates).

MI_LO_HANDLE *LO_hdl = NULL;
MI_LO_STAT *LO_stat = NULL;
MI_LO_SPEC *LO_spec;
MI_LO_FD new_LOfd, old_LOfd;
...
if ( mi_lo_stat(conn, old_LOfd, &LO_spec) != MI_OK )
   {
   /* handle error and exit */
   }
LO_spec = mi_lo_stat_cspec(LO_stat);
new_LOfd = mi_lo_create(conn, LO_spec, flags, &LO_hdl);