Home |
Previous Page | Next Page Data Manipulation > Using Smart Large Objects > Using the Smart-Large-Object Interface >
The smart-large-object interface includes functions that
provide the following operations on a smart large object:
- Creating a smart large object
- Performing input and output (I/O) on
smart-large-object data
- Manipulating LO handles
- Accessing storage characteristics
- Obtaining status information
- Moving smart large objects to and from operating-system files
Most of the smart-large-object function names begin with the
string 'mi_lo_'. The IBM Informix: DataBlade API Function Reference contains an alphabetical list of
all DataBlade API functions, including the smart-large-object functions.
Functions
That Create a Smart Large Object
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. Table 29 lists the smart-large-object creation functions.
Table 29. 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( )
(deprecated) |
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.
Functions That Perform Input and Output on a Smart Large
Object
The smart-large-object interface for Dynamic Server 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.
Table 30 shows the basic file-like
operations on a smart large object with the smart-large-object function
that performs them and the analogous operating-system calls for file
operations.
Table 30. Main DataBlade API Functions of the Smart-Large-Object Interface
| 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( ) |
For more information, see Opening
a Smart Large Object.
Functions
That Manipulate an LO Handle
The following table shows the smart-large-object
functions that act on an LO handle, not
on the smart large object that it identifies.
- 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( )
(deprecated)
- 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 transient 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. There is no guarantee that the internal structure of MI_LO_HANDLE will
not change. To create portable code, use the appropriate DataBlade API function
to access this structure.
For more information on how to use these functions, see Obtaining
an LO Handle.
Functions That Access an LO-Specification
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( )
(deprecated) |
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_flags( ) |
Retrieves the default open mode from the LO-specification
structure |
| mi_lo_specget_estbytes( ) |
Retrieves 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_flags( ) |
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. The internal structure of MI_LO_SPEC may
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.
Functions That Access an LO-Status
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 seconds component
of the last-modification time |
| mi_lo_stat_mtime_usec( ) |
Accessor function to get the microseconds component
of 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. The internal structure of MI_LO_STAT may
change in future releases. Therefore, to create portable code, always
use the LO-status accessor functions to obtain and store values
from this structure.
For more information on how to use these functions, see Obtaining
Status Information.
Functions That Move 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.
| 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 |
For more information on how to use these functions, see Using Operating-System
Files.
Home |
[ Top of Page | Previous Page | Next Page | Contents |
Index ]