OCILobLoadFromFile()

Purpose

Load/copy all or a portion of the file into an internal LOB.

Syntax

sword OCILobLoadFromFile ( OCISvcCtx        *svchp, 
                           OCIError         *errhp, 
                           OCILobLocator    *dst_locp, 
                           OCILobLocator    *src_locp, 
                           ub4              amount, 
                           ub4              dst_offset, 
                           ub4              src_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.

dst_locp (IN/OUT)

A locator uniquely referencing the destination internal LOB which may be of type BLOB, CLOB, or NCLOB.

src_locp (IN/OUT)

A locator uniquely referencing the source FILE.

amount (IN)

The number of bytes to be loaded.

dst_offset (IN)

This is the absolute offset for the destination LOB. For character LOBs it is the number of characters from the beginning of the LOB at which to begin writing. For binary LOBs it is the number of bytes from the beginning of the LOB from which to begin reading. The offset starts at 1.

src_offset (IN)

This is the absolute offset for the source FILE. It is the number of bytes from the beginning of the FILE. The offset starts at 1.

Comments

Loads/copies a portion or all of a FILE value into an internal LOB as specified. The data is copied from the source FILE to the destination internal LOB (BLOB/CLOB). No character set conversions are performed when copying the FILE data to a CLOB/NCLOB. Also, when binary data is loaded into a BLOB, no character set conversions are performed. Therefore, the FILE data must already be in the same character set as the LOB in the database. No error checking is performed to verify this.

The source (src_locp) and the destination (dst_locp) LOBs must already exist. If the data already exists at the destination's start position, it is overwritten with the source data. If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination LOB from the end of the data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB.

It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes) or to try to copy from a NULL FILE.

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(), OCILobAppend(), OCILobWrite(), OCILobTrim(), OCILobCopy(), OCILobGetLength(), OCILobWriteAppend()