INFORMIX
DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions
Home Contents Index Master Index New Book

mi_lo_copy()

 The mi_lo_copy() function creates a copy of a smart large object and opens the copy.

Syntax

Usage

 The mi_lo_copy() function performs the following steps to create a new smart large object whose data is copied from the smart large object that src_LOhdl references:

    1. It obtains an LO handle for the new smart large object and assigns a pointer to the LO handle that target_LOhdl_dptr references.

    If the *target_LOhdl_dptr value points to NULL, mi_lo_copy() allocates a new LO handle for the new smart large object and assigns a pointer to this handle to *target_LOhdl_dptr. If *target_LOhdl_dptr does not point to NULL, mi_lo_copy() assumes that you have already allocated an LO handle and uses the target_LOhdl_dptr argument as a pointer to an existing LO handle.

    2. It assigns the storage characteristics from the LO-specification structure, LO_spec, to the new smart large object.

    If the LO-specification structure has not been updated with storage characteristics (the associated fields are null), the mi_lo_copy() function uses the system-specified storage characteristics.

    3. It opens the new smart large object in the open mode that the flags argument specifies.

    4. It copies the contents of the data in the smart large object that src_LOhdl references into the new smart large object that target_LOhdl_dptr references.

    The mi_lo_copy() function writes the source data to the sbspace of the new smart large object.

    5. It returns an LO file descriptor that identifies the new smart large object and is positioned at the start of this smart large object.

    When the mi_lo_copy() function is successful, it returns a valid LO file descriptor. You can then use this file descriptor to identify which smart large object to access in subsequent function calls, such as mi_lo_read() and mi_lo_write().

Each mi_lo_copy() call is implicitly associated with the current session. When this session ends, the database server deallocates any smart large objects that are not referenced by any columns (those with a reference count of zero).

Tip: The mi_lo_copy() function replaces the mi_large_object_copy() function, which Informix supports for backward compatibility only. Use mi_lo_copy() for all new DataBlade routines.

Return Values

An MI_LO_FD

The LO file descriptor for the open smart large object that target_LOhdl_dptr references. The function also initializes the LO handle that target_LOhdl_dptr references.

MI_ERROR

The function was not successful.

Related Topics

 See the descriptions of the following functions: mi_lo_create(), mi_lo_expand(), mi_lo_from_file(), mi_lo_spec_init(), and mi_lo_open().

In Chapter 3, "Handling Smart Large Objects," see "Initializing an LO Handle and LO File Descriptor".



DataBlade API Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.