op_id_from_userid()
Abstract
Obtains the object ID of an object specified by parent, object type, and user ID.
Syntax
op_id_from_userid (parent_objid, obj_type, userid)
| Argument | Type | Description |
|---|---|---|
parent_objid |
int |
object ID of the object-of-interest’s parent For subnet, node, link, or tap objects, the parent object is always a subnet object. |
obj_type |
int |
type of the object-of-interest This value is a numeric code that specifies the type of the object-of-interest (see Table 69 “Object Type Symbolic Constants“ on page 19). Object types for this KP are limited to network domain objects. The acceptable symbolic constants for this argument are: OPC_OBJTYPE_SUBNET_FIXOPC_OBJTYPE_NODE_FIXOPC_OBJTYPE_NODE_MOBOPC_OBJTYPE_NODE_SATOPC_OBJTYPE_LKSIMPOPC_OBJTYPE_LKDUPOPC_OBJTYPE_LKBUSOPC_OBJTYPE_LKTAP |
userid |
int |
user ID of the object-of-interest This value is a user-defined integer which is compared to the user id attribute of network-domain objects. |
Return Type
Objid
Object ID of the specified object.
The special value represented by the symbolic constant OPC_OBJID_INVALID will be returned if a recoverable error occurs.
Example
/* determine local node object ID */
local_objid = op_topo_parent (op_id_self ());
/* obtain the site number from attribute */
op_ima_obj_attr_get (local_objid, "site no", &site_no);
/* obtain the object IDs of four neighbor nodes */
objid_north = op_id_from_userid (0, OPC_OBJTYPE_NODE_FIX, site_no + DIR_NORTH);
objid_south = op_id_from_userid (0, OPC_OBJTYPE_NODE_FIX, site_no + DIR_SOUTH);
objid_east = op_id_from_userid (0, OPC_OBJTYPE_NODE_FIX, site_no + DIR_EAST);
objid_west = op_id_from_userid (0, OPC_OBJTYPE_NODE_FIX, site_no + DIR_WEST);
Details
The object-of-interest is specified to this KP via three arguments: its parent’s object ID, its type, and its user ID (a user-defined integer assigned to the user id attribute of network-domain objects). This KP is designed to be used in situations where user IDs are not duplicated in multiple objects of the same type which are contained in the same parent object. If this criteria does not hold (for instance, if two nodes in the same subnet have the same user ID), then it is unspecified which of the matching objects will be returned. However, no error will occur.
Purpose
Provides a mechanism to map object user IDs into object IDs. The usual application of this KP is to obtain the object ID of a node using a numeric identifier, rather than the name identifier used by the KP op_id_from_name(). If user IDs are carefully assigned to objects so that they are unique and contiguous, they can be used as the index of a loop that scans all objects of a particular type.
Errors
- Recoverable Error: Object ID (
<parent_objid>) is out-of-range. - Recoverable Error: Object (
<parent_objid>) has no children. - Recoverable Error: Object type (
<obj_type>) is out-of-range. - Recoverable Error: Object (
<parent_objid>) has no child with user ID (<userid>) of specified type. - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KP op_id_from_name() to obtain the object ID of an object from its name
- Use the KP op_ima_obj_attr_get() to obtain the value of an object’s attribute
- Use the KP op_ima_obj_attr_set() to assign the value of an object’s attribute