OCIObjectCopy()

Purpose

Copies a source instance to a destination.

Syntax

sword OCIObjectCopy ( OCIEnv              *env,
                      OCIError            *err, 
                      CONST OCISvcCtx     *svc,
                      dvoid               *source, 
                      dvoid               *null_source, 
                      dvoid               *target, 
                      dvoid               *null_target, 
                      OCIType             *tdo,
                      OCIDuration         duration, 
                      ub1                 option );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

An OCI service context handle, specifying the service context on which the copy operation is taking place

source (IN)

A pointer to the source instance; if it is an object, it must be pinned.

null_source (IN)

Pointer to the null structure of the source object.

target (IN)

A pointer to the target instance; if it is an object is must be pinned.

null_target (IN)

A pointer to the null structure of the target object.

tdo (IN)

The TDO for both the source and the target. Can be retrieved with OCIDescribeAny().

duration (IN)

Allocation duration of the target memory.

option (IN)

This parameter is currently unused. Pass as zero or OCI_DEFAULT.

Comments

This function copies the contents of the source instance to the target instance. This function performs a deep-copy such that all of the following is copied:

• all the top level attributes (see the exceptions below)
• all secondary memory (of the source) reachable from the top level attributes
• the null structure of the instance

Memory is allocated with the duration specified in the duration parameter.

Certain data items are not copied:

• If the option OCI_OBJECTCOPY_NOREF is specified in the option parameter, then all references in the source are not copied. Instead, the references in the target are set to null.
• If the attribute is an internal LOB, then only the LOB locator from the source object is copied. A copy of the LOB data is not made until OCIObjectFlush() is called. Before the target object is flushed, both the source and the target locators refer to the same LOB value.

The target or the containing instance of the target must be already have been created. This may be done with OCIObjectNew() or OCIObjectPin() depending on whether or not the target object already exists.

The source and target instances must be of the same type. If the source and target are located in a different databases, then the same type must exist in both databases.

Related Functions

OCIObjectPin()