The lld_copy() function

This function copies the specified large object.

Syntax

MI_ROW* lld_copy(conn, src, dest, error); 
   MI_CONNECTION*               conn, 
   MI_ROW*                      src, 
   MI_ROW*                      dest,
   mi_integer*                  error

ifx_collection_t* lld_copy (src, dest, error);
   EXEC SQL BEGIN DECLARE SECTION;
      PARAMETER ROW src;
      PARAMETER ROW dest;
   EXEC SQL END DECLARE SECTION;
   int* error;

CREATE FUNCTION LLD_Copy (src LLD_Locator, dest LLD_Locator)
   RETURNS LLD_Locator; 

conn

The connection descriptor established by a previous call to the mi_open() or mi_server_connect() function. This parameter is for the API interface only. In the ESQL/C and SQL versions of this function, you must already be connected to a server.

src

A pointer to the lld_locator row, identifying the source object.

dest

A pointer to an lld_locator row, identifying the destination object. If the destination object itself does not exist, it is created.

error

An output parameter in which the function returns an error code. The SQL version of this function does not have an error parameter.

Usage

This function copies an existing large object.

If the destination object exists, pass a pointer to its lld_locator row as the dest parameter.

If the destination object does not exist, pass an lld_locator row with the following values as the dest parameter to lld_copy():

In the lo_protocol field, specify the type of large object to create.

The lld_copy() function creates the type of large object that you specify, copies the source object to it, and returns the row you passed, unaltered.

If you are copying to a smart large object, specify NULL for the lo_pointer and lo_location fields of the lld_locator row that you pass as the dest parameter. The lld_copy() function returns an lld_locator row with a pointer to the new smart large object in the lo_pointer field.

The server deletes a new smart large object at the end of a transaction if there are no disk references to it and if it is closed. Therefore, after copying to a newly created smart large object, either open it or insert it into a table.

If lld_copy() creates a new smart large object, it uses system defaults for required storage parameters such as sbspace. If you want to override these parameters, you can use the server large object interface to create the smart large object and specify the parameters you want in an MI_LO_SPEC structure. You can then call lld_copy() and set the lo_pointer field of the lld_locator row to point to the new smart large object.

Likewise, if protocols are added to Large Object Locator for new types of large objects, these objects might require creation attributes or parameters for which Large Object Locator supplies predefined default values. As with smart large objects, you can create the object with lld_copy() and accept the default values, or you can use the creation routines specific to the new protocol and supply your own attributes and parameters. After you create the object, you can call lld_copy() and pass it an lld_locator row that points to the new object.

Return codes

On success, this function returns a pointer to an lld_locator row, specifying the location of the copy of the large object. If the destination object already exists, lld_copy() returns a pointer to the unaltered lld_locator row you passed in the dest parameter. If the destination object does not already exist, lld_copy() returns a pointer to an lld_locator row, pointing to the new object it creates.

On failure, this function returns NULL.

Context

The lld_from_client() function

The lld_to_client() function