1. Select the smart large object from the database into an ifx_lo_t host variable with the SELECT statement.

2. Open the smart large object with the ifx_lo_open() function.

3. Perform the appropriate read or write operations to update the data of the smart large object.

4. Close the smart large object with the ifx_lo_close() function.

A CLOB or BLOB column in a database table contains the LO-pointer structure for a smart large object. Therefore, when you select a CLOB or BLOB column into an ifx_lo_t host variable, the SELECT statement returns an LO-pointer structure. For this reason, you declare host variables for CLOB and BLOB values as LO-pointer structures. (For more information, see "Declaring a Host Variable".)

Figure 7-5 shows how the database server transfers the data of a smart large object to the ESQL/C client application.

Figure 7-5 Transferring Smart- Large-Object Data from Database Server to Client Application

For a sample of code that selects a smart large object from a database column, see "The create_clob Program". For information on how to store a smart large object in the database, see page 7-17.

Opening a Smart Large Object

Access Modes

Figure 7-6 shows the access modes and their corresponding defined constants that the ifx_lo_open() and ifx_lo_create() functions support.

Figure 7-6
Access-Mode Flags for Smart Large Objects

Access Mode	Purpose	Access-Mode Constant
Read-only mode	Only read operations are valid on the data.	LO_RDONLY
Write-only mode	Only write operations are valid on the data.	LO_WRONLY
Write/append mode	Appends any data you write to the end of the smart large object. By itself, it is equivalent to write-only mode followed by a seek to the end of the smart large object. Read operations fail.	LO_APPEND
Read/write mode	Both read and write operations are valid on the data.	LO_RDWR
Buffered access	Use standard database server buffer pool.	LO_BUFFER
Lightweight I/O	Use private buffers from the session pool of the database server.	LO_NOBUFFER

Tip: These access-mode flags for a smart large object are patterned after the UNIX System V access modes.

When you open a smart large object with LO_APPEND only, the smart large object is opened as read-only. Seek operations move the file pointer but write operations to the smart large object fail and the file pointer is not moved from its position just before the write. Read operations occur from where the file pointer is positioned and then the file pointer is moved.

You can mask the LO_APPEND flag with another access mode. In any of these OR combinations, the seek operation remains unaffected. The following table shows the effect on the read and write operations that each of the OR combinations has.

OR Operation	Read Operations	Write Operations
LO_RDONLY | LO_APPEND	Occur at the file position and then move the file position to the end of the data that has been read	Fail and do not move the file position.
LO_WRONLY | LO_APPEND	Fail and do not move the file position	Move the file position to the end of the smart large object and then write the data; file position is at the end of the data after the write.
LO_RDWR | LO_APPEND	Occur at the file position and then move the file position to the end of the data that has been read	Move the file position to the end of the smart large object and then write the data; file position is at the end of the data after the write.

Lightweight I/O

Lightweight I/O allows you to bypass the overhead of the least-recently-used (LRU) queues that the database server uses to manage the buffer pool. For more information about LRUs, see the INFORMIX-Universal Server Performance Guide.

You can specify lightweight I/O by setting the flags parameter to LO_NOBUFFER when you create a smart large object with the ifx_lo_create() function or when you open a particular smart large object with the ifx_lo_open() function. To specify buffered access, which is the default, use the LO_BUFFER flag.

Important: Keep the following issues in mind when you use lightweight I/O:

• Close smart large objects with ifx_lo_close() when you are finished with them to free memory allocated to the private buffers.
• All opens that use lightweight I/O for a particular smart large object share the same private buffers. Consequently, one operation can cause the pages in the buffer to be flushed while other operations expect the object to be present in the buffer.

• You can use the ifx_lo_alter() function to switch a smart large object from lightweight I/O (LO_NOBUFFER) to buffered I/O (LO_BUFFER) if the smart large object is not open. However, ifx_lo_alter() generates an error if you try to change a smart large object that uses buffered I/O to one that uses lightweight I/O.
• Unless you first use ifx_lo_alter() to change the access mode to buffered access (LO_BUFFER), you can only open a smart large object that was created with lightweight I/O with the LO_NOBUFFER access-mode flag. If an open specifies LO_BUFFER, the database server ignores the flag.
• You can open a smart large object that has been created with buffered access (LO_BUFFER) with the LO_NOBUFFER flag only if you open the object in read-only mode. If you attempt to write to the object, the database server returns an error. To write to the smart large object, you must close it then reopen it with the LO_BUFFER flag and an access flag that allows write operations.

Smart-Large-Object Locks

You use the access-mode flags, LO_RDONLY, LO_APPEND, LO_WRONLY, LO_RDWR, and LO_TRUNC to specify the lock mode of a smart large object. You pass these flags to the ifx_lo_open() and ifx_lo_create() functions. When you specify LO_RDONLY, the database server places a share lock on the smart-large-object data. If you specify any other access-mode flag, the database server obtains an update lock, which it promotes to an exclusive lock on first write or other update operation.

Share and update locks (read-only mode, or write mode before an update operation occurs) are held until your program takes one of the following actions:

• Closes the smart large object
• Commits the transaction or rolls it back

Important: You lose the lock at the end of a transaction, even if the smart large object remains open. When the database server detects that a smart large object has no active lock, it automatically obtains a new lock when the first access occurs to the smart large object. The lock it obtains is based on the original open mode of the smart large object.

Duration of an Open on a Smart Large Object

• The ifx_lo_close() function closes the smart large object.
• The session ends.

Warning: The end of the current transaction does not close a smart large object. It does, however, release any lock on a smart large object.

• The current transaction commits.
• The smart large object is closed, if the application opened the smart large object.

1. Read and write the data in the open smart large object until the data is ready to save.

2. Store the LO-pointer for the smart large object in the database with the UPDATE or INSERT statement.

Reading Data From a Smart Large Object

The ifx_lo_read() and ifx_lo_readwithseek() functions require a valid LO file descriptor to identify the smart large object to be read. You obtain an LO file descriptor with the ifx_lo_open() or ifx_lo_create() function. For more information, see the descriptions of the ifx_lo_read() function on page 7-55 and the ifx_lo_readwithseek() function on page 7-57.

Writing Data to a Smart Large Object

The ifx_lo_write() and ifx_lo_writewithseek() functions require a valid LO file descriptor to identify the smart large object to write. You obtain an LO file descriptor with the ifx_lo_open() or ifx_lo_create() function. For more information, see the descriptions of the ifx_lo_write() function on page 7-96 and the ifx_lo_writewithseek() function on page 7-98.

Closing a Smart Large Object