OCILobAssign()

Purpose

Assigns one LOB/FILE locator to another.

Syntax

sword OCILobAssign ( OCIEnv                *envhp, 
                     OCIError              *errhp, 
                     CONST OCILobLocator   *src_locp, 
                     OCILobLocator         **dst_locpp );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

src_locp (IN)

LOB/FILE locator to copy from.

dst_locpp (IN/OUT)

LOB/FILE locator to copy to. The caller must have allocated space for the destination locator by calling OCIDescriptorAlloc().

Comments

Assign source locator to destination locator. After the assignment, both locators refer to the same LOB value. For internal LOBs, the source locator's LOB value gets copied to the destination locator's LOB value only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator will copy the LOB value.

OCILobAssign() cannot be used for temporary LOBs; it will generate an OCI_INVALID_HANDLE error. For temporary LOBs, use OCILobLocatorAssign().

For FILEs, only the locator that refers to the file is copied to the table. The operating system file itself is not copied.

It is an error to assign a FILE locator to an internal LOB locator, and vice versa.

If the source locator is for an internal LOB that was enabled for buffering, and the source locator has been used to modify the LOB data through the LOB buffering subsystem, and the buffers have not been flushed since the write, then the source locator may not be assigned to the destination locator. This is because only one locator for each LOB may modify the LOB data through the LOB buffering subsystem.

The value of the input destination locator must have already been allocated with a call to OCIDescriptorAlloc(). For example, assume the following declarations:

OCILobLocator     *source_loc = (OCILobLocator *) 0;
OCILobLocator     *dest_loc = (OCILobLocator *) 0;

An application could allocate the source_loc locator as follows:

if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &source_loc,
    (ub4) OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0))
    handle_error;

Assume that it then selects a LOB from a table into the source_loc in order to initialize it. The application must allocate the destination locator, dest_loc, before issuing the OCILobAssign() call to assign the value of source_loc to dest_loc. For example:

if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &dest_loc,
    (ub4)OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0))
    handle_error;
if (OCILobAssign(envhp, errhp, source_loc, &dest_loc)) 
    handle_error;

Related Functions

OCIErrorGet(), OCILobIsEqual(), OCILobLocatorAssign(), OCILobLocatorIsInit(), OCILobEnableBuffering()