Create a new smart large object
page 3-32
Access data in an existing smart large object
page 3-60
Modify an existing smart large object
page 3-72
Obtain status information about an existing smart large object
page 3-74
Delete a smart large object
page 3-80
Tip: The DataBlade API also supports the Illustra large-object interface for backward compatibility with Illustra products. Smart-Large-Object Data Structures The INFORMIX-Universal Server smart-large-object interface provides data structures that store information about a smart large object. Figure 3-4 summarizes the data structures of the smart-large-object interface.
Figure 3-4 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 routine; 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 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 them on disk. For a description of the storage characteristics available, see "Storage Characteristics".
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
To access an LO-specification structure in a DataBlade routine, 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:
The LO Handle 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. To access an LO handle in a DataBlade routine, declare it in one of the following ways:
The 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:
0
The LO-Status Structure The LO-status structure, MI_LO_STAT, contains the status information for an existing smart large object. To access an LO-status structure in a DataBlade routine, 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:
Smart-Large-Object Functions The INFORMIX-Universal Server smart-large-object interface includes functions that provide the following operations on a smart large object:
Smart-Large-Object Creation The smart-large-object creation functions create a new smart large object, open it, and return a valid LO handle and LO file descriptor for it. Figure 3-5 lists the smart-large-object creation functions.
Figure 3-5 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 For more information on how to use the smart-large-object creation functions, see "Creating a Smart Large Object".
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
Smart-Large-Object I/O The INFORMIX-Universal Server smart-large-object interface includes functions that provide basic file operations such as create, open, seek, read, write, alter, and truncate. These functions 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 3-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 system calls for file operations.
Figure 3-6 Main DataBlade API Functions of the Smart-Large-Object Interface Smart-Large-Object Operation Smart-Large-Object Function Operating-System 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() 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() 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 deallocate the LO file descriptor. mi_lo_close() close() For more information, see "Opening a Smart Large Object".
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()
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()
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 deallocate the LO file descriptor.
mi_lo_close()
close()
Manipulation of LO Handles The following table shows the smart-large-object functions that act on an LO handle, not on the smart large object that it represents.
(1 of 2)
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
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
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
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
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
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 routines. 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. For more information on how to use these functions, see "Obtaining an LO Handle".
Smart-Large-Object Storage Characteristics The following table shows the smart-large-object functions that access the LO-specification structure.
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
Copies the contents of the smart large object into a new smart large object, whose storage characteristics the LO-specification structure contains
Creates a new smart large object that has the storage characteristics in the LO-specification structure
Copies multirepresentational data into a new smart large object, whose storage characteristics the LO-specification structure contains
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_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_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 routines. 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. For more information on how to use these functions, see "Obtaining the LO-Specification Structure" and "Choosing Storage Characteristics".
Smart-Large-Object Status The following table shows the smart-large-object functions that access the LO-status structure.
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
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()
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 routines. 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 values from this structure. For more information on how to use these functions, see "Obtaining the Status of a Smart Large Object".
Smart Large Objects to and from Operating-System Files The following table shows the smart-large-object functions that move smart large objects to and from operating-system files.
mi_file_to_file()
Copies the contents of one operating-system file to another
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
Copies the contents of a smart large object to a new operating-system file
For more information on how to use these functions, see "Using Operating-System Files".
