The lld_create() function

This function creates a new large object with the protocol and location you specify.

Syntax

MI_ROW* lld_create(conn, lob, error)
   MI_CONNECTION*               conn
   MI_ROW*                      lob;
   mi_integer*                  error;

ifx_collection_t* lld_create (lob, error);
   EXEC SQL BEGIN DECLARE SECTION;
      PARAMETER ROW lob;
   EXEC SQL END DECLARE SECTION;
   int* error;

CREATE FUNCTION LLD_Create (lob 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.

lob

A pointer to an lld_locator row, identifying the object to create.

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

You pass an lld_locator row, with the following values, as the lob parameter to lld_create():

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

The lld_create() function returns the row you passed, unaltered.

If you are creating a smart large object, specify NULL for the lo_pointer and lo_location fields of the lld_locator row. The lld_create() 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 creating a smart large object, either open it or insert it into a table.

Large Object Locator does not directly support transaction rollback, except for smart large objects. Therefore, if the transaction in which you call lld_create() is aborted, you should call lld_delete() to delete the object and reclaim any allocated resources.

See Large object requirements for more information.

When you create a smart large object, lld_create() 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_create() 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_create() 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_create() 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 new large object. For a smart large object, lld_create() returns a pointer to the location of the new object in the lo_pointer field of the lld_locator row. For all other objects, it returns a pointer to the unaltered lld_locator row you passed in the lob parameter.

The lld_open function can use the lld_locator row that lld_create() returns.

On failure, this function returns NULL.

Context

The lld_delete() function

The lld_open() function