OCILobLocatorAssign()

Purpose

Assigns one LOB/FILE locator to another.

Syntax

sword OCILobLocatorAssign ( OCISvcCtx            *svchp,
                            OCIError             *errhp,
                            CONST OCILobLocator  *src_locp,
                            OCILobLocator         **dst_locpp );

Parameters

svchp (IN/OUT)

The OCI service context handle.

errhp (IN/OUT)

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

src_locp (IN)

The LOB/FILE locator to copy from.

dst_locpp (IN/OUT)

The LOB/FILE locator to copy to. The caller must allocate space for the OCILobLocator by calling OCIDescriptorAlloc().

Comments

This call assigns the source locator to the destination locator. After the assignment, both locators refer to the same LOB data. For internal LOBs, the source locator's LOB data gets copied to the destination locator's LOB data only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator copies the LOB data. For FILEs only the locator that refers to the OS file is copied to the table; the OS file is not copied.

Note that this call is similar to OCILobAssign() but OCILobLocatorAssign() takes an OCI service handle pointer instead of an OCI environment handle pointer. Also, OCILobLocatorAssign() can be used for temporary LOBs and OCILobAssign() cannot be used for temporary LOBs.

Note: If the OCILobLocatorAssign() function fails, the target locator will not be restored to its previous state. The target locator should not be used in subsequent operations unless it is reinitialized.

If the destination locator is for a temporary LOB, the destination temporary LOB is freed before assigning the source LOB locator to it.

If the source LOB locator refers to a temporary LOB, the destination will be made into a temporary LOB too. The source and the destination will conceptually be different temporary LOBs. In the OCI_DEFAULT mode, the source temporary LOB is deep copied and a destination locator is created to refer to the new deep copy of the temporary LOB. Hence OCILobIsEqual() will return FALSE after the OCILobLocatorAssign() call. However, in the OCI_OBJECT mode, an optimization is made to minimize the number of deep copies, so the source and destination locators will point to the same LOB until any modification is made through either LOB locator. Hence OCILobIsEqual() will return TRUE right after OCILobLocatorAssign() until the first modification. In both these cases, after the OCILobLocatorAssign(), any changes to the source or the destination will not reflect in the other (that is, destination or source) LOB. If you want the source and the destination to point to the same LOB and want your changes to reflect in the other, then you must use the equal sign to ensure that two LOB locator pointers refer to the same LOB locator.

Related Functions

OCIErrorGet(), OCILobAssign(), OCILobIsEqual(), OCILobLocatorIsInit()