The lld_from_client() function

This function copies a client file to a large object.

Syntax

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

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

CREATE FUNCTION LLD_FromClient(src LVARCHAR, 
                  dest LLD_Locator) 
   RETURNS LLD_Locator;

conn

The connection descriptor established by a previous call to the mi_open() or mi_server_connect() functions. 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 source path name.

dest

A pointer to the destination lld_locator row. 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_from_client().

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

The lld_from_client() function creates the type of large object that you specify, copies the source file 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_from_client() 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 you copy to a newly created smart large object, either open it or insert it into a table.

If lld_from_client() 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_from_client() 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_from_client() 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_from_client() and pass it an lld_locator row that points to the new object.

Return codes

On success, returns a pointer to an lld_locator row that specifies the location of the copy of the large object. If the destination object already exists, lld_from_client() returns a pointer to the unaltered lld_locator row that you created and passed in the dest parameter. If the destination object does not already exist, lld_from_client() returns an lld_locator row that points to the new object it creates.

On failure, this function returns NULL.

Context

The lld_create_client() function

The lld_open_client() function