The ifx_lo_create() function

The ifx_lo_create() function creates a new smart large object and opens it for access within the program.

Syntax

mint ifx_lo_create(LO_spec, flags, LO_ptr, error)
   ifx_lo_create_spec_t *LO_spec;
   mint flags;
   ifx_lo_t *LO_ptr;
   mint *error;
LO_spec
A pointer to the LO-specification structure that contains the storage characteristics for new smart large objects. For information about the LO-specification structure, see The LO-specification structure.
flags
An integer that specifies the mode in which to open the new smart large object. For more information, see Access modes.
LO_ptr
A pointer to the LO-pointer structure for the new smart large object. For more information about LO-pointer structures, see The LO-pointer structure.
error
A pointer to an integer that contains the error code that ifx_lo_create() sets.

Usage

The ifx_lo_create() function performs the following steps to create a new smart large object:
  1. It creates a LO-pointer structure and assigns a pointer to this structure to the LO_ptr argument.
  2. It assigns the storage characteristics for the smart large object from the LO-specification structure, LO_spec.

    If the LO-specification structure does not contain storage characteristics (the associated fields are null), ifx_lo_create() uses the storage characteristics from the inheritance hierarchy for the new smart large object. The ifx_lo_create() function also uses the system-specified storage characteristics if the LO_spec pointer is null.

    For more information about the inheritance hierarchy, see Obtain storage characteristics.

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

    The flag values for the flags argument indicate the mode of the smart large object after ifx_lo_create() successfully completes. Valid values include all access-mode constants, which Access-mode flags for smart large objects shows. For more information about access modes, see Open a smart large object.

  4. It returns an LO file descriptor that identifies the open smart large object.
Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call the ifx_lo_create() function.

HCL OneDB™ uses the default parameters that the call to ifx_lo_create() establishes to determine whether subsequent operations result in locking and/or logging of the corresponding smart large object. For more information, see Lightweight I/O

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

If the ifx_lo_create() function is successful, it returns a valid LO-file descriptor (LO_fd). You can then use the LO_fd to identify which smart large object to access in subsequent function calls such as ifx_lo_read() and ifx_lo_write(). However, a LO_fd is only valid within the current database connection.

Return codes

A valid LO file descriptor
The function successfully created and opened the new smart large object.
-1
The function was not successful; examine the error for a detailed error code.