OCILobErase()

Purpose

Erases a specified portion of the internal LOB data starting at a specified offset.

Syntax

sword OCILobErase ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amount,
                    ub4             offset );

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)

An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp.

amount (IN/OUT)

The number of characters for CLOBs/NCLOBs or bytes for BLOBs to erase. On IN, the value signifies the number of characters or bytes to erase. On OUT, the value identifies the actual number of characters or bytes erased.

offset (IN)

Absolute offset in characters for CLOBs/NCLOBs or bytes for BLOBs from the beginning of the LOB value from which to start erasing data. Starts at 1.

Comments

The actual number of characters/bytes erased is returned. For BLOBs, erasing means that zero-byte fillers overwrite the existing LOB value. For CLOBs, erasing means that spaces overwrite the existing LOB value.

This function is valid only for internal LOBs; FILEs are not allowed.

It is not mandatory that you wrap this LOB operation inside the Open/Close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, 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.

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. 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(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()