The ifx_lo_open() function

The ifx_lo_open() function opens an existing smart large object for access.

Syntax

mint ifx_lo_open(LO_ptr, flags, error)
   ifx_lo_t *LO_ptr;
   mint flags;
   mint *error;

LO_ptr: A pointer to the LO-pointer structure that identifies the smart large object to open.
flags: A mint that specifies the mode in which to open the smart large object that LO_ptr identifies.
error: A pointer to a mint that contains the error code that ifx_lo_open() sets.

Usage

Your program must call the ifx_lo_open() function for each instance of a smart large object that it needs to access.

The value of the flags argument indicates the mode of the smart large object after ifx_lo_open() successfully completes. For a description of valid values for the flags argument, see Access-mode flags for smart large objects.

HCL OneDB™ uses the default parameters that ifx_lo_open() (or ifx_lo_create()) establishes to determine whether subsequent operations cause locking or logging to occur for the smart large object. For more information about the settings that affect the opening of a smart large object, see Open a smart large object.

Each ifx_lo_open() 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_open() function is successful, it returns a valid LO file descriptor (LO_fd). You can then use the file descriptor to identify which smart large object to access in subsequent function calls such as ifx_lo_read() and ifx_lo_write(). A LO_fd is valid only within the current database connection.

After ifx_lo_open() has opened the smart large object, it sets the seek position in the returned LO file descriptor to byte 0. If the default range for locking is set for locking the entire smart large object, the ifx_lo_open() function can also obtain a lock on the smart large object, based on the following settings for the access mode:

For dirty-read mode, the database server does not place a lock on the smart large object.
For read-only mode, the database server obtains a shared lock on the smart large object.
For write-only, write-append, or read-write mode, the database server obtains an update lock on the smart large object. When a call to the ifx_lo_write() or ifx_lo_writewithseek() function occurs, the database server promotes the lock to an exclusive lock.

The lock that ifx_lo_open() obtains is lost when the current transaction terminates. The database server obtains the lock again, however, when the next function that needs a lock executes. If this behavior is undesirable, use BEGIN WORK transaction blocks and place a COMMIT WORK or ROLLBACK WORK statement after the last statement that needs to use the lock.

Return codes

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