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

obj (IN)

The object whose property is returned.

propertyId (IN)

The identifier that specifies the property.

property (OUT)

The buffer into which the specified property is copied.

size (IN/OUT)

On input, this parameter specifies the size of the property buffer passed by the caller.

On output, it contains the size in bytes of the property returned. This parameter is required for string-type properties only, such as OCI_OBJECTPROP_SCHEMA and OCI_OBJECTPROP_TABLE. For non-string properties this parameter is ignored because the size is fixed.

Comments

This function returns the specified property of the object. This property is identified by propertyId. The property value is copied into property and for string typed properties, the string size is returned by size.

Objects are classified as persistent, transient, and value depending upon the lifetime and referenceability of the object. Some of the properties are applicable only to persistent objects and some others apply only to persistent and transient objects. An error is returned if the user tries to get a property that is not applicable to the given object. To avoid such an error, first check whether the object is persistent or transient or value (OCI_OBJECTPROP_LIFETIME property) and then appropriately query for other properties.

The different property IDs and the corresponding type of property argument are given next.

OCI_OBJECTPROP_LIFETIME

This identifies whether the given object is a persistent object or a transient object or a value instance. The property argument must be a pointer to a variable of type OCIObjectLifetime. Possible values include:

OCI_OBJECT_PERSISTENT

OCI_OBJECT_TRANSIENT

OCI_OBJECT_VALUE

OCI_OBJECTPROP_SCHEMA

This returns the schema name of the table in which the object exists. An error is returned if the given object points to a transient instance or a value. If the input buffer is not big enough to hold the schema name, an error is returned; the error message communicates the required size. Upon success, the size of the returned schema name in bytes is returned by size. The property argument must be an array of type text, and size should be set to size of array in bytes by the caller.

OCI_OBJECTPROP_TABLE

This returns the table name in which the object exists. An error is returned if the given object points to a transient instance or a value. If the input buffer is not big enough to hold the table name, an error is returned; the error message communicates the required size. Upon success, the size of the returned table name in bytes is returned by size. The property argument must be an array of type text, and size should be set to size of array in bytes by the caller.

OCI_OBJECTPROP_PIN_DURATION

This returns the pin duration of the object. An error is returned if the given object points to a value instance. The property argument must be a pointer to a variable of type OCIDuration. Valid values include:

This returns the lock status of the object. The possible lock statuses are enumerated by OCILockOpt. An error is returned if the given object points to a transient or value instance. The property argument must be a pointer to a variable of type OCILockOpt. The lock status of an object can also be retrieved by calling OCIObjectIsLocked(). Valid values include:

This returns the dirty status and indicates whether the object is a new object, updated object, or deleted object. An error is returned if the given object points to a transient or value instance. The property argument must be of type OCIObjectMarkStatus. Valid values include:

OCI_OBJECT_NEW

OCI_OBJECT_DELETED

OCI_OBJECT_UPDATED

The following macros are available to test the object mark status:

OCI_OBJECT_IS_UPDATED (flag)

OCI_OBJECT_IS_DELETED (flag)

OCI_OBJECT_IS_NEW (flag)

OCI_OBJECT_IS_DIRTY (flag)

OCI_OBJECTPROP_VIEW

This identifies whether the specified object is a view object or not. If the property value returned is TRUE, the object is a view; otherwise, it is not. An error is returned if the given object points to a transient or value instance. The property argument must be of type boolean.