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 source temporary LOB is deep copied and a destination locator is created to refer to the new deep copy of the temporary LOB. To avoid this deep copy, the user should use the equal sign to ensure that two LOB locator pointers refer to the same LOB locator.

Related Functions

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