OCILobClose()

Purpose

Closes a previously opened LOB or FILE.

Syntax

sword OCILobClose ( OCISvcCtx      *svchp,
                    OCIError       *errhp, 
                    OCILobLocator  *locp );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

locp (IN/OUT)

The LOB to close. The locator can refer to an internal or external LOB.

Comments

Closes a previously opened internal or external LOB. No error is returned if the BFILE exists but is not opened. An error is returned if the internal LOB is not open.

Closing a LOB requires a round- trip to the server for both internal and external LOBs. For internal LOBs, close will trigger other code that relies on the close call and for external LOBs (BFILEs), close actually closes the server-side operating system file.

It is not mandatory that you wrap all LOB operations inside the Open/Close calls. However, if you open a LOB, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column. It is an error to commit the transaction before closing all opened LOBs that were opened by the transaction.

When the error is returned, the LOB is no longer marked as open, but the transaction is successfully committed. Hence, all the changes made to the LOB and non-LOB data in the transaction are committed but the domain and functional indexing are not updated. If this happens, please rebuild your functional and domain indexes on the LOB column.

If you do not wrap your LOB operations inside the Open/Close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance, so if you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open/close statements.

Related Functions

OCIErrorGet(), OCILobOpen(), OCILobIsOpen()