A pointer to the target instance; if it is an object, it 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 information is copied:

All the top-level attributes (see the exceptions later)

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 have been created. This can be done with OCIObjectNew() or OCIObjectPin() depending on whether the target object exists.

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

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().

instance (IN)

Pointer to an object.

null_struct (IN)

The NULL structure of the object or array.

tdo (IN)

Pointer to the type descriptor object (TDO).

names (IN)

Array of attribute names. This is used to specify the names of the attributes in the path expression.

lengths (IN)

Array of lengths of attribute names, in bytes.

name_count (IN)

Number of elements in the array names.

indexes (IN) [optional]

Not currently supported. Pass as (ub4 *)0.

index_count (IN) [optional]

Not currently supported. Pass as (ub4)0.

attr_null_status (OUT)

The NULL status of the attribute if the type of attribute is primitive.

attr_null_struct (OUT)

This parameter is filled only for object and opaque attributes, not for collections. For collections (pass OCICollGetElem), attr_null_struct is NULL. For collections, this parameter indicates if the entire collection is NULL or not.

attr_value (OUT)

Pointer to the attribute value.

attr_tdo (OUT)

Pointer to the TDO of the attribute.

Comments

This function gets a value from an object or from an array. If the parameter instance points to an object, then the path expression specifies the location of the attribute in the object. It is assumed that the object is pinned and that the value returned is valid until the object is unpinned.

If both attr_null_status and attr_null_struct are NULL, no NULL information is returned.

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().

object (IN)

A pointer to the persistent object being locked. It must already be pinned.

Comments

This function locks a persistent object at the server. However, unlike OCIObjectLock(), this function does not wait if another user holds the lock on the object and an error is returned if the object is currently locked by another user. This function also returns an error for transient objects and values, or objects that do not exist.

Pointer to the type descriptor object. The TDO describes the type of the instance that is to be created. See OCITypeByName() for obtaining a TDO. The TDO is required for creating a named type, such as an object or a collection.

table (IN) [optional]

Pointer to a table object that specifies a table in the server. This parameter can be set to NULL if no table is given. See the following description to learn how the table object and the TDO are used together to determine the kind of instances (persistent, transient, value) to be created. Also see OCIObjectPinTable() for retrieving a table object.

duration (IN)

This is an overloaded parameter. The use of this parameter is based on the kind of the instance that is to be created. See Table 18-10 for more information.

For a persistent object type of instance, this parameter specifies the pin duration.

For a transient object type of instance, this parameter specifies the allocation duration and pin duration.

For a value type of instance, this parameter specifies the allocation duration.

value (IN)

Specifies whether the created object is a value. If TRUE, then a value is created. Otherwise, a referenceable object is created. If the instance is not an object, then this parameter is ignored.

instance (OUT)

Address of the newly created instance. The instance can be a character string in UTF-16 (Unicode) if the environment handle has the appropriate setting and the object is OCIString.

Comments

This function creates a new instance of the type specified by the typecode or the TDO. It can create an OCIString object with a Unicode buffer if the typecode indicates the object to be created is OCIString.

Table 18-10 shows that based on the parameters typecode (or tdo), value, and table, different instances are created.

Table 18-10 Instances Created

Type of the Instance

Table != NULL

Table == NULL

object type (value=TRUE)

value

value

object type (value=FALSE)

persistent object

transient object

built-in type

value

value

collection type

value

value

This function allocates the top-level memory chunk of an instance. The attributes in the top-level memory are initialized, which means that an attribute of VARCHAR2 is initialized to an OCIString of 0 length. If the instance is an object, the object is marked existent but is atomically NULL.

The object is marked dirty and existent. The allocation duration for the object is session. The object is pinned, and the pin duration is specified by the given parameter duration. Creating a persistent object does not cause any entries to be made into a database table until the object is flushed to the server.

For Transient Objects

The object is pinned. The allocation duration and the pin duration are specified by the given parameter duration.

For Values

The allocation duration is specified by the given parameter duration.

Attribute Values of New Objects

By default, all attributes of a newly created object have NULL values. After initializing attribute data, the user must change the corresponding NULL status of each attribute to non-NULL.

It is possible to have attributes set to non-NULL values when an object is created. This is accomplished by setting the OCI_ATTR_OBJECT_NEWNOTNULL attribute of the environment handle to TRUE using OCIAttrSet(). This mode can later be turned off by setting the attribute to FALSE. If OCI_ATTR_OBJECT_NEWNOTNULL is set to TRUE, then OCIObjectNew() creates a non-NULL object.

If the object contains an internal LOB attribute, the LOB is set to empty. The object must be marked as dirty and flushed (to insert the object into the table) and repinned before the user can start writing data into the LOB. When pinning the object after creating it, you must use the OCI_PIN_LATEST pin option to retrieve the newly updated LOB locator from the server.

If the object contains an external LOB attribute (FILE), the FILE locator is allocated but not initialized. The user must call OCILobFileSetName() to initialize the FILE attribute before flushing the object to the database. It is an error to perform an INSERT or UPDATE operation on a FILE without first indicating a directory object and file name. Once the file name is set, the user can start reading from the FILE.