Using the Smart-Large-Object Interface

The smart-large-object interface allows you to access the data of a smart large object in much the same way as you would access an operating-system file in the UNIX or Windows NT operating systems. The interface provides the following:

The milo.h header file defines the functions and data structures of the smart-large-object interface. The mi.h header file automatically includes the milo.h header file. You must include either mi.h or milo.h in any DataBlade API routine that calls a smart-large-object function or declares one of the smart-large-object data structures.

Sections of this chapter describe how to use the smart-large-object interface to perform the following operations on a smart large object.

Smart-Large-Object Operation	For More Information
Create a new smart large object	page 6-33
Access data in an existing smart large object	page 6-61
Modify an existing smart large object	page 6-76
Obtain status information about an existing smart large object	page 6-79
Delete a smart large object	page 6-84

Tip: The DataBlade API also supports the Illustra Large-Object interface for backward compatibility with Illustra products. For more information, see Using the Illustra Large-Object Interface.

Smart-Large-Object Data Structures

The smart-large-object interface provides data structures that store information about a smart large object. Figure 6-4 summarizes the data structures of the smart-large-object interface.

Smart-Large-Object Data 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.

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.

Default 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.

The 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. It contains encoded information about the smart large object, such as its physical disk location and other security-related information. Once a smart large object is created, an associated LO handle is a valid reference for the life of that smart large object.

Default Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_get_lo_handle(), mi_lo_copy(), mi_lo_create(), mi_lo_create(), mi_lo_from_buffer(), mi_lo_from_file(), mi_lo_from_string()
	Destructor	mi_lo_release()

To access an LO handle in a user-defined routine, 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.

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:

The following table summarizes the memory operations for an LO file descriptor.

Default Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_lo_copy(), mi_lo_create(), 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.

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

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.

Default 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 the Status of a Smart Large Object.

The smart-large-object interface includes functions that provide the following operations on a smart large object:

Most of the smart-large-object functions begin with the string mi_lo_. Chapter 15, DataBlade API Function Descriptions, contains an alphabetical list of all DataBlade API functions, including the smart-large-object functions.

The smart-large-object creation functions create a new smart large object, open it, and return a new LO handle and LO file descriptor for it. Figure 6-5 lists the smart-large-object creation functions.

Smart-Large-Object Creation Function	Description
mi_lo_create()	Creates a new, empty smart large object
mi_lo_copy()	Creates a new smart large object that is a copy of an existing smart large object
mi_lo_expand()	Creates a new smart large object from existing multirepresentational data
mi_lo_from_file()	Creates a new smart large object from data in an operating-system file

The Dynamic Server smart-large-object interface includes functions that provide basic file operations such as create, open, seek, read, write, alter, and truncate. These routines bypass the query processor, executor, and optimizer, and give the application direct access to a smart large object. These functions use an LO file descriptor to identify the open smart large object.

Figure 6-6 shows the basic file-like operations on a smart large object along with the smart-large-object function that performs them and the analogous operating-system calls for file operations.

Smart-Large-Object Operation	Smart-Large-Object Function	Operating-System Call
Open the smart large object that the `LO` handle identifies: the open operation generates an `LO` file descriptor for the smart large object.	mi_lo_open()	open()
Seek to the desired `LO` seek position to begin a read or write operation.	mi_lo_seek()	seek()
Obtain the current `LO` seek position.	mi_lo_tell()	tell()
Lock the specified number of bytes of data.	mi_lo_lock()	lock()
Perform the read or write operation for the specified number of bytes.	mi_lo_read(), mi_lo_readwithseek(), mi_lo_write(), mi_lo_writewithseek()	read(), write()
Unlock the specified number of bytes of data.	mi_lo_unlock()	unlock()
Obtain status information about a particular smart large object.	mi_lo_stat()	stat()
Truncate smart-large-object data at a specified location.	mi_lo_truncate()	truncate()
Close the smart large object and free the `LO` file descriptor.	mi_lo_close()	close()

The following table shows the smart-large-object functions that act on an LO handle, not on the smart large object that it represents.

DataBlade API Function	Purpose
mi_get_lo_handle()	Obtains an `LO` handle from a user-defined buffer
mi_lo_alter()	Alters the storage characteristics of the smart large object that the `LO` handle identifies
mi_lo_copy()	Copies the contents of a smart large object (that an `LO` handle identifies) into a new smart large object and initializes the `LO` handle of the new smart large object
mi_lo_create()	Creates a new smart large object and initializes its `LO` handle
mi_lo_decrefcount()	Decrements the reference count of the smart large object that the `LO` handle identifies
mi_lo_expand()	Copies multirepresentational data into a new smart large object and initializes the `LO` handle
mi_lo_filename()	Returns the name of the file where the mi_lo_to_file() function would store the smart large object that the `LO` handle identifies
mi_lo_from_buffer()	Copies a specified number of bytes from a user-defined buffer into a smart large object that the `LO` handle identifies
mi_lo_from_file()	Copies the contents of an operating-system file to a smart large object that the `LO` handle identifies
mi_lo_from_string()	Converts an `LO` handle from its text representation to its binary representation
mi_lo_increfcount()	Increments the reference count of the smart large object that the `LO` handle identifies
mi_lo_invalidate()	Marks an `LO` handle as invalid
mi_lo_lolist_create()	Converts an array of `LO` handles into an `MI_LO_LIST` structure
mi_lo_open()	Opens the smart large object that the `LO` handle identifies
mi_lo_ptr_cmp()	Compares two `LO` handles to see if they identify the same smart large object
mi_lo_release()	Releases resources held by a temporary smart large object, including its `LO` handle
mi_lo_to_buffer()	Copies a specified number of bytes from a smart large object that the `LO` handle identifies into a user-defined buffer
mi_lo_to_file()	Copies the smart large object that the `LO` handle identifies to an operating-system file
mi_lo_to_string()	Converts an `LO` handle from its binary representation to its text representation
mi_lo_validate()	Checks whether an `LO` handle is valid
mi_put_lo_handle()	Puts an `LO` handle into a user-defined buffer

Important: The LO handle, MI_LO_HANDLE, is an opaque structure to DataBlade API modules. Do not access its internal structure directly. Informix does not guarantee that the internal structure of MI_LO_HANDLE will not change. Therefore, to create portable code, use the appropriate DataBlade API function to use this structure.

The following table shows the smart-large-object functions that access the LO-specification structure.


DataBlade API Function	Purpose
mi_lo_alter()	Alters the storage characteristics of an existing smart large object
mi_lo_colinfo_by_ids()	Updates the `LO`-specification structure with the column-level storage characteristics for a column identified by a row descriptor
mi_lo_colinfo_by_name()	Updates the `LO`-specification structure with the column-level storage characteristics for a column identified by name
mi_lo_copy()	Copies the contents of the smart large object into a new smart large object, whose storage characteristics the `LO-`specification structure contains
mi_lo_create()	Creates a new smart large object that has the storage characteristics in the `LO-`specification structure
mi_lo_expand()	Copies multirepresentational data into a new smart large object, whose storage characteristics the `LO-`specification structure contains
mi_lo_from_file()	Copies the contents of an operating-system file to a smart large object, whose storage characteristics the `LO-`specification structure contains
mi_lo_spec_free()	Frees the resources of the `LO`-specification structure
mi_lo_spec_init()	Allocates and initializes an `LO`-specification structure
mi_lo_specget_def_open()	Accessor function to get the default open mode from the `LO`-specification structure
mi_lo_specget_estbytes()	Accessor function to get the estimated number of bytes from the `LO`-specification structure
mi_lo_specget_extsz()	Accessor function to get the allocation extent size from the `LO`-specification structure
mi_lo_specget_flags()	Accessor function to get the attributes flag from the `LO`-specification structure
mi_lo_specget_maxbytes()	Accessor function to get the maximum number of bytes from the `LO`-specification structure
mi_lo_specget_sbspace()	Accessor function to get the name of the sbspace from the `LO`-specification structure
mi_lo_specset_def_open()	Accessor function to set the default open mode in the `LO`-specification structure
mi_lo_specset_estbytes()	Accessor function to set the estimated number of bytes in the `LO`-specification structure
mi_lo_specset_extsz()	Accessor function to set the allocation extent size in the `LO`-specification structure
mi_lo_specset_flags()	Accessor function to set the attribute flags in the `LO`-specification structure
mi_lo_specset_maxbytes()	Accessor function to set the maximum number of bytes in the `LO`-specification structure
mi_lo_specset_sbspace()	Accessor function to set the name of the sbspace in the `LO`-specification structure
mi_lo_stat_cspec()	Returns a pointer to the `LO`-specification structure that contains the storage characteristics obtained from the `LO`-status structure of an existing smart large object

Important: The LO-specification structure, MI_LO_SPEC, is an opaque structure to DataBlade API modules. Do not access its internal structure directly. Informix does not guarantee that the internal structure of MI_LO_SPEC will not change in future releases. Therefore, to create portable code, always use the LO-specification accessor functions to obtain and store values in this structure.

The following table shows the smart-large-object functions that access the LO-status structure.

DataBlade API Function	Purpose
mi_lo_stat()	Allocates and initializes an `LO`-status structure with status information of an open smart large object
mi_lo_stat_atime()	Accessor function to get the last-access time
mi_lo_stat_cspec()	Accessor function to get the storage characteristics
mi_lo_stat_ctime()	Accessor function to get the last-change time
mi_lo_stat_free()	Frees the resources of the `LO`-status structure
mi_lo_stat_mtime_sec()	Accessor function to get the last-modification time
mi_lo_stat_refcnt()	Accessor function to get the reference count
mi_lo_stat_size()	Accessor function to get the size of smart large object

Important: The LO-status structure, MI_LO_STAT, is an opaque structure to DataBlade API modules. Do not access its internal structure directly. Informix does not guarantee that the internal structure of MI_LO_STAT will not change in future releases. Therefore, to create portable code, always use the LO-status accessor functions to obtain and store values from this structure.

The following table shows the smart-large-object functions that move smart large objects to and from operating-system files.

DataBlade API Function	Purpose
mi_file_to_file()	Copies the contents of one operating-system file to another
mi_lo_from_file()	Copies the contents of an operating-system file to a new smart large object
mi_lo_from_file_by_lofd()	Copies the contents of an operating-system file to an existing smart large object
mi_lo_to_file()	Copies the contents of a smart large object to a new operating-system file

Informix DataBlade API Programmer's Manual
Using Smart Large Objects