op_topo_assoc()
Abstract
Obtains the object ID of an object’s association having the specified type, direction, and index.
Syntax
op_topo_assoc (objid, direction, objmtype, index)
| Argument | Type | Description |
|---|---|---|
objid |
Objid |
object ID of the reference object [An object ID can be obtained from several KPs in the Id package: op_id_self(), op_id_from_userid(), and op_id_from_name(). In addition, object IDs can be obtained from prior invocations of the Topo package KPs op_topo_parent(), op_topo_child(), and op_topo_connect().] |
direction |
int |
direction of associationOPC_TOPO_ASSOC_IN for input associationsOPC_TOPO_ASSOC_OUT for output associationsOPC_TOPO_ASSOC_THROUGH for throughput associations |
objmtype |
int |
object meta-type of association [This value is an integer code that specifies the object type of the association-of-interest (see Table 69 “Object Type Symbolic Constants“ on page 19).] |
index |
int |
numeric index of the association-of-interest [Association indices start at 0 and increment by one.] |
Return Type
Objid
Object ID of the specified input or output association. The special value represented by the symbolic constant OPC_OBJID_INVALID will be returned if a recoverable error occurs.
Example
Excerpt from: example model (models/std/sdr); process model (sdr); state (INIT); enter execs.
/* Set up routing and interface tables. */
num_out_assoc = op_topo_assoc_count (loc_mod_objid, OPC_TOPO_ASSOC_OUT,
OPC_OBJTYPE_STRM);
for (i = 0; i < num_out_assoc; i++)
{
strm_objid = op_topo_assoc (loc_mod_objid, OPC_TOPO_ASSOC_OUT,
OPC_OBJTYPE_STRM, i);
op_ima_obj_attr_get (strm_objid, "src stream", &strm);
if (strm != 0)
. . .
}
Details
The input and output associations of an object are the objects directly connected to its input and output ports (respectively) or a path that begins or ends at a node (respectively). “Through” associations are primarily useful for referencing any paths that run to, from, or through a particular object; or for referencing any objects connected to a particular path.
Table 21 lists the valid reference object/association type pairs.
Table 21: Objects and Associated Types
| Ref. Object Type | In | Out | Through |
|---|---|---|---|
| site (fixed subnet; fixed node) | site, link, path | site, link, path | path |
| link (bus; simplex, duplex pt-pt link) | site transmitter | site receiver | path |
| path | site (destination) | site (source) | all attached nodes/links, all demands flowing through |
| demand | site (destination) | site (source) | all paths used |
| module (processor, queue, and so on) | module connection | module connection | none |
| connection (stream, statistic wire) | module | module | none |
| transmitter (pt-pt, bus, radio) | module connection | link receiver | none |
| receiver (pt-pt, bus, radio) | link transmitter | module connection | none |
| tap | bus, bus transmitter | bus, bus receiver | none |
| bus transmitter | none | tap | none |
| bus receiver | tap | none | none |
| bus | tap | tap | none |
In wireless modeling, mobile and satellite sites cannot be connected to a point-to-point or bus link, so only path and demand associations are possible. Also, wireless domains do not have associations.
This KP uses forced serialization, as described in “Multi-Threading Safety“ on page 11.
Purpose
Provides a mechanism to obtain an object ID of an object that is attached to an input or output of the reference object. This is typically a useful function when a process needs to obtain or assign attributes that belong to adjacent objects. For example, a process running on a processor connected to a transmitter may need to periodically change the frequency of the transmitter’s channels; another scenario might involve a process querying the attributes of an outgoing point-to-point link.
Errors
- Recoverable Error: Object ID (
<objid>) is out-of-range. - Recoverable Error: Association direction (
<dir>) is unrecognized. - Recoverable Error: Object meta-type (
<objmtype>) is unrecognized. - Recoverable Error: Assoc. index (
<index>) is out-of-range. - Recoverable Error: Object type (
<objmtype>) doesn’t support associations. - Recoverable Error: Assoc. direction (
<direction>) is not supported by ref. object. - Recoverable Error: Assoc index (
<index>) exceeds assocs of type (<objmtype>). - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KP op_topo_assoc_count() to determine the number of associations an object has
- Use the KP op_ima_obj_attr_get() to obtain the value of an object’s attribute