op_ima_obj_attr_exists()
Abstract
Determines whether an attribute is defined for the specified object.
Syntax
op_ima_obj_attr_exists (objid, attr_name)
| Argument | Type | Description |
|---|---|---|
objid |
Objid |
object ID of the object-of-interest [An object ID can be obtained from several KPs in the Topo and Id packages, including: op_id_self(), op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
attr_name |
const char* |
name of the attribute-of-interest |
Return Type
Boolean
Boolean indicating whether the specified attribute is defined for the object of interest.
This value will be equal to the constant OPC_TRUE if the attribute is defined; otherwise the return value will be OPC_FALSE.
Example
/* Up to MAX_DESTS destinations are allowed for this traffic source process. */
/* Each one will be specified by an attribute. Determine which destinations */
/* are specified (Attributes only exist for defined destinations). */
for (d = 0; d < MAX_DESTS; d++)
{
/* Compose a name for the destination attribute. */
sprintf (name, "destination_%d", d);
/* Test for its existence to see if the destination is defined. */
/* If it is defined, proceed with configuration for that dest. */
if (op_ima_obj_attr_exists (node_objid, name) == OPC_TRUE)
configure_destination (d);
/* If not, assume there are no others. */
else break;
}
Details
In some cases, attributes are defined on a conditional basis for an object. In particular, promoted attributes and extended attributes may or may not be present for a given object. Also attribute names may be dependent on information which is determined dynamically. In such cases, a process or pipeline stage may need to test for the presence of an attribute via op_ima_obj_attr_exists() prior to obtaining or modifying its value. Although the KPs op_ima_obj_attr_set() and op_ima_obj_attr_get() return a completion code of OPC_COMPCODE_FAILURE when a non-existent attribute is referenced, this code also can indicate other types of failures. Furthermore, a recoverable error message is generated when an undefined attribute is accessed via these KPs.
Purpose
Object attributes may be dynamically obtained or modified using the KPs op_ima_obj_attr_get() and op_ima_obj_attr_set(). However, these KPs assume that the object of interest maintains the desired attribute. An error occurs if these KPs are used to access an attribute that is not present. The KP op_ima_obj_attr_exists() can be used prior to using the access KPs in order to prevent such errors when it is not known with certainty that an attribute is defined.
Errors
- Program Abort: Segmentation violation (due to an invalid address for
attr_name) - Recoverable Error: Object ID (
<objid>) is out-of-range. - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KPs op_ima_obj_attr_get(), op_ima_obj_attr_get_dbl(), op_ima_obj_attr_get_int32(), op_ima_obj_attr_get_objid(), op_ima_obj_attr_get_str(), and op_ima_obj_attr_get_toggle() to obtain the value of an object attribute
- Use the KPs op_ima_obj_attr_set(), op_ima_obj_attr_set_dbl(), op_ima_obj_attr_set_int32(), op_ima_obj_attr_set_objid(), op_ima_obj_attr_set_str(), and op_ima_obj_attr_set_toggle() to assign a value to an object attribute
- Use the KP op_id_self() to obtain the object ID of the surrounding processor or queue
- Use the KP op_id_from_name() to obtain the object ID of an arbitrary object