Smart-Large-Object Data Type Structures

The smart-large-object interface provides data type structures that store information about a smart large object. Table 28 summarizes the data type structures of the smart-large-object interface.

Table 28. Data Types of the Smart-Large-Object Interface
Smart-Large-Object Data Type Structure	Data Type	Description
The LO-specification structure	MI_LO_SPEC	Holds storage characteristics for a smart large object
The LO handle	MI_LO_HANDLE	Identifies the location of the smart large object; analogous to the filename of an operating-system file
The LO file descriptor	MI_LO_FD	Identifies an open smart large object; analogous to the file descriptor of an operating-system file
The LO-status structure	MI_LO_STAT	Holds status information about a smart large object

These structures are all opaque to a DataBlade API module; that is, you do not access their fields directly but instead use accessor functions that the smart-large-object interface provides.

LO-Specification Structure

The LO-specification structure, MI_LO_SPEC, defines the storage characteristics for an existing or a new smart large object. The storage characteristics provide information about features of the smart large object and how to store it on disk. For a description of the storage characteristics available, see Storage Characteristics.

The following table summarizes the memory operations for an LO-specification structure.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_lo_spec_init( )
Destructor	mi_lo_spec_free( )

To access an LO-specification structure in a DataBlade API module, declare a pointer to an MI_LO_SPEC structure. For example, the following line shows the valid syntax of a variable that accesses an LO-specification structure:

Declaration of a flat LO-specification structure generates a compile error. The following line shows invalid syntax for an LO-specification structure:

The milo.h header file defines the MI_LO_SPEC data type. Therefore, you must include the milo.h (or mi.h) file in DataBlade API modules that access this structure. For information on how to use an LO-specification structure, see Obtaining the LO-Specification Structure.

LO Handle

An LO handle, MI_LO_HANDLE, serves as a reference to a smart large object. It is analogous to the filename of an operating-system file in that it is a unique identifier of a smart large object. The LO handle contains encoded information about the smart large object, such as its physical disk location and other security-related information. After a smart large object is created, an associated LO handle is a valid reference for the life of that smart large object.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_get_lo_handle( ), mi_lo_copy( ), mi_lo_create( ), mi_lo_expand( ), mi_lo_from_buffer( ), mi_lo_from_string( ), mi_streamread_lo( )
Destructor	mi_lo_delete_immediate( ), mi_lo_release( )

To access an LO handle in a user-defined routine (UDR), declare it in one of the following ways:

The milo.h header file defines the MI_LO_HANDLE data type. Therefore, you must include the milo.h (or mi.h) file in DataBlade API modules that access this handle. For information on how to use an LO handle, see Initializing an LO-Specification Structure and Selecting the LO Handle.

LO File Descriptor

The LO file descriptor, MI_LO_FD, is a reference to an open smart large object. An LO file descriptor is similar to a file descriptor for an operating-system file. It is an integer number that serves as a transient descriptor for performing I/O on the data of the smart large object. It provides the following information about an open smart large object:

Memory Duration	Memory Operation	Function Name
Not allocated from memory-duration pools	Constructor	mi_lo_copy( ), mi_lo_create( ), mi_lo_expand( ), mi_lo_from_file( ), mi_lo_open( )
Destructor	mi_lo_close( )

To access an LO file descriptor in a DataBlade API module, declare a variable with the MI_LO_FD data type. For example, the following line declares the variable my_lofd that is an LO file descriptor:

The milo.h header file defines the MI_LO_FD data type. Therefore, you must include the milo.h (or mi.h) file in DataBlade API modules that access this handle.

Other smart-large-object data type structures require that you declare a pointer to them because the DataBlade API handles memory allocation for these structures. However, you can declare an LO file descriptor directly.

Because you declare an LO file descriptor directly, its scope is that of the variable you declare to hold it. When you assign an LO file descriptor to a local variable, the LO file descriptor is deallocated when the function that declares it ends. If you want to keep the LO file descriptor longer, you can allocate user memory with the memory duration you want (up to the advanced duration of PER_SESSION) and copy the LO file descriptor into this memory. For example, you could assign the LO file descriptor to PER_COMMAND memory and copy it into the user state of the MI_FPARAM structure. For more information, see Managing the Memory Duration and Saving a User State.

Important:

Although the scope of an LO file descriptor is determined by its declaration, the scope of the open smart large object (which the LO file descriptor identifies) is the entire session. Make sure you explicitly close a smart large object before the scope of its LO file descriptor expires. For more information, see Freeing a Smart Large Object.

LO-Status Structure

The LO-status structure, MI_LO_STAT, contains the status information for an existing smart large object. The following table summarizes the memory operations for an LO-status structure.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_lo_stat( )
Destructor	mi_lo_stat_free( )

To access an LO-status structure in a DataBlade API module, declare a pointer to an MI_LO_STAT structure. For example, the following line declares the variable mystat that points to an LO-specification structure:

Declaration of a flat LO-status structure generates a compile error. The following line shows invalid syntax for an LO-status structure:

The milo.h header file defines the MI_LO_STAT data type. Therefore, you must include the milo.h (or mi.h) file in DataBlade API modules that access this structure. For information on how to allocate and use an LO-status structure, see Obtaining Status Information.