Attribute / Component / Values (ACVs)

Each of the operators listed in the previous section has one or more EMA library functions that implement it. Most operator functions have one or more arguments that identify the model or object to which they are being applied. However, the attribute get and set functions have a special interface with regard to arguments. For increased conciseness and efficiency, these functions allow multiple attributes of a model or an object to be accessed or assigned at the same time. This feature is supported via the passing of variable numbers of arguments, based on the varargs interface that is part of the standard set of C language support.

Each individual attribute operation is specified in terms of a trio of arguments:

  • Attribute
  • Component
  • Value

The Attribute argument specifies which attribute of an object or model is to be manipulated. The Component argument specifies which of several components of the attribute is to be manipulated (up until now, the only attribute component that has been described in this document is the attribute “contents”). The Value argument specifies a variable or constant that will be used as the source or destination for the value of one of the attribute's components. This trio of arguments is known as an ACV, and the sequence of ACVs that composes the arguments to the attr_get and attr_set operators is known as the ACV List. ACV Lists are terminated by the symbolic constant EMAC_EOL (i.e., the EMA symbolic constant indicating the end-of-list).

The following lines illustrate these concepts:

	<ACV> = <attribute_arg>, <component_arg>, <value_arg>
	<ACV List> = <ACV>, <ACV>, ..., EMAC_EOL

The component facility is provided to support the manipulation of attributes that have type modifiers, such as array or toggle attributes. Explanation of the various attribute components will now be presented, along with examples of value declarations for attributes of each core type.

Contents Component

The component of an attribute that has already been introduced, and that is used most often in operator calls, is the contents of the attribute. This component is indicated by setting the second argument of an ACV to the symbolic constant COMP_CONTENTS.

The ACV form of the contents component is:

	<attr_name>, COMP_CONTENTS, <value>

Depending on the core type of the attribute, the variable used as the value of the ACV should be declared and passed differently, as listed in the following table. Also note that ACVs in attr_set operators can contain constant values that match the C data type of the attribute’s core type (e.g., integer & object ID (10), double (10.1112), or string (“constant”)); all of the argument conventions of the C language will apply.

Table 4: COMP_CONTENTS Value Types

Core Type Value Declaration Operator ACV Form
integer int var; attr_get
attr_set
A, C, &var
A, C, var
double double var; attr_get
attr_set
A, C, &var
A, C, var
string char var [256]; attr_get
attr_set
A, C, var
A, C, var
textlist PrgT_List *var; attr_get
attr_set
A, C, &var
A, C, var
object ID EmaT_Object_Id var; attr_get
attr_set
A, C, &var
A, C, var

Array Contents Component

The array contents component is used when getting or setting the contents of attributes that have the array type modifier. These types of attributes present a special requirement that prohibits the use of the regular COMP_CONTENTS symbolic constant: the index of the array element must be passed to the operator, so that it can find the unique array element that should be manipulated. The array index requirement is accomplished by a macro that is passed as the second argument of an ACV: COMP_ARRAY_CONTENTS(). This macro takes its own argument, which is the index of the desired array element. If an attempt is made to get or set the contents of an element with an index that is beyond the current array size, the array will be expanded to that size (within the bounds of the array's memory limit).

The ACV form of the array contents component is:

	<attr_name>, COMP_ARRAY_CONTENTS(<array_index>), <value>

Despite the modified form of the ACV’s middle argument, the value types for the COMP_CONTENTS component listed in Table 4 still apply to this component.

Array Symbolic Contents Component

The array symbolic contents component is used when getting or setting the symbolic contents of attributes that have the array type modifier. This component is almost identical to the array contents component described previously. The difference is that the value of a symbolic contents is always a string (either identifying that no symbolic value exists, or providing the name of a symbolic value). The symbolic constant EMAC_NO_SYMBOL is used to specify no symbolic value.

The ACV form of the array symbolic contents component is:

	<attr_name>, COMP_ARRAY_CONTENTS_SYMBOL(<array_index>), <value>

Array Size Component

Arrays in EMA are numerically indexed lists of elements; the number of elements contained in the array is termed the size of the array, and is stored in the array size component. This component can be obtained via the attr_get operator, with the second argument of an ACV set to the symbolic constant COMP_ARRAY_SIZE. The array size component cannot be set using this method, since this component is get-only. Using the attr_get and attr_set operators, it is possible to extend an array beyond its default size. It is not possible to shrink an array down to a smaller size, however (i.e., array size is monotonic).

Most array attributes have zero default sizes, but some have preset initial sizes for added convenience. The ACV form of the array size component appears below; the value must always be an integer pointer.

	<attr_name>, COMP_ARRAY_SIZE, &var

Double Vector Contents Component

The double vector contents component is used when getting or setting the contents of attributes that are of the double vector core type. As with array attributes, double vector attributes present a special requirement that prohibits the use of the regular COMP_CONTENTS symbolic constant: the index of the vector element must be passed to the operator, so that it can find the unique vector element that should be manipulated. The vector index requirement is accomplished by a macro that is passed as the second argument of an ACV: COMP_DVEC_CONTENTS(). This macro takes a single argument, which is the index of the desired vector element. If an attempt is made to get or set the contents of an element with an index that is beyond the current vector size, an error will result (note that this is different from array attributes, which automatically extend to fit “out-of-range” accesses).

The ACV form of the double vector contents component is:

	<attr_name>, COMP_DVEC_CONTENTS(<vector_index>), <value>

Despite the modified form of the ACVs middle argument, the value types for the COMP_CONTENTS component listed in Table 4 still apply to this component.

Double Vector Size Component

Double vector attributes are numerically indexed lists of elements; the number of elements contained in the vector is termed the size of the vector, and is stored in the double vector size component. This component can be obtained via the attr_get operator, with the second argument of an ACV set to the symbolic constant COMP_DVEC_SIZE. A double vector attribute cannot be automatically extended using an “out-of-range” index in an attr_set or attr_get operator; the only way to change the size of a double vector attribute is by using an attr_set operator with the component COMP_DVEC_SIZE. Therefore, this component is both gettable and settable.

Most double vector attributes have zero default sizes, but some have preset initial sizes for added convenience. If a double vector attribute has a default size of zero, its size must be set using the double vector size component before any attr_set or attr_get operators are applied to the double vector contents component.

The ACV form of the double vector size component is:

attr_get: <attr_name>, COMP_DVEC_SIZE, &var

attr_set: <attr_name>, COMP_DVEC_SIZE, var

Toggle Component

Attributes that have the toggle type modifier can be placed in the enabled or disabled state. Getting or setting the toggle of the attribute can be done via the toggle component. This component is indicated by setting the second argument of an ACV to the symbolic constant COMP_TOGGLE. The state of the attribute is independent of the attribute's contents, which is set as usual via the COMP_CONTENTS component. The two ACV forms of the toggle component appear below; the value must be an integer pointer for the attr_get operator or an integer for the attr_set operator.

attr_get: <attr_name>, COMP_TOGGLE, &var

attr_set: <attr_name>, COMP_TOGGLE, var

Symbolic Contents Component

The symbolic contents component is similar to the contents component, except that the value is a string indicating the symbolic value of the attribute. The symbolic constant EMAC_NO_SYMBOL is used to specify no symbolic value.

The ACV form of the symbolic contents component is:

	<attr_name>, COMP_CONTENTS_SYMBOL, <value>

Type Component

As mentioned previously, certain EMA object attributes are not defined to have a single specific type, but to take on many possible types (the poly type). The type component of an attribute specifies which of the different supported types the attribute’s value will represent. Valid constants for the value are the integer constants EMAC_INTEGER, EMAC_DOUBLE, EMAC_STRING, EMAC_TOGGLE, EMAC_TOGGLE_DOUBLE, EMAC_DATAFILE, and EMAC_COMPOUND.

The two ACV forms of the type component appear below. The value must be an integer pointer for the attr_get operator and an integer for the attr_set operator.

attr_get: <attr_name>, COMP_CONTENT_TYPE, &var

attr_set: <attr_name>, COMP_CONTENT_TYPE, var

Set Component

It is often necessary to determine if a particular attribute has been set or not, particularly if the attribute type is an optional object ID. These attributes will not have well-defined values if they have not been set (since there is no default value for object IDs). Thus accessing and utilizing their contents can cause errors if they have not been set. A convenient mechanism for determining if an attribute has been set is provided via the set component of each attribute. This get-only component can be accessed by an ACV with the second argument set to the symbolic constant COMP_SET.

The ACV form of the set component appears below. The value must always be an integer pointer.

	<attr_name>, COMP_SET, &var

Object Type Component

EMA supports several built-in attributes for models (described in EMA Built-In Attributes). One of these attributes, ATTR_EMA_NUM_OBJECTS, provides a mechanism for obtaining from EMA the number of objects of a particular type that are contained in a model. Since models usually have several types of objects, the ATTR_EMA_NUM_OBJECTS attribute must have several components associated with it. Each component keeps track of the quantity of a particular type of object. All of these components are specified by setting the second argument of an ACV to the macro COMP_OBTYPE(). As with COMP_ARRAY_SIZE(), this component itself takes a single argument. However, instead of being an index, the argument to this component is a symbolic constant which identifies the type of object being inquired about. For instance, if the number of “A” objects is needed for a computation, then COMP_OBTYPE() will take the argument OBJ_A.

The ACV form of the object type component is shown below. Because the number of objects cannot be set directly using ATTR_EMA_NUM_OBJECTS, these components are get-only. Therefore, the value must always be an integer pointer.

	ATTR_EMA_NUM_OBJECTS, COMP_OBTYPE(<object_type>), &var

Promote Component

The environment architecture of Riverbed analysis software supports attributes at several different modeling levels (for instance, attributes can be associated with process models, processors, nodes, subnets, and the simulation as a whole). One advanced feature of the architecture is that it supports “promotion” of attributes associated with lower-level entities to higher-level entities. An example of this is that attributes defined at the process model level are automatically promoted to be attributes of the parent processor or queue (i.e., the module that is executing the process model). This allows the attributes to be assigned values on a module-by-module basis. If attributes are not assigned values at the module level, then the attributes will be automatically promoted to the node level; one more recursion of this type promotes the attributes to the simulation-wide level.

Built-in attributes of objects are not promoted by default; instead, when an object is created, its built-in attributes have default assigned values. To promote built-in attributes, a specific tool operation must be performed. However, user-defined attributes of objects (or models, in the case of process models) are automatically promoted. When a value is assigned to a promoted attribute, the attribute is then unpromoted, since it does not need to seek a value assignment at a higher level.

In EMA, the promotion of an attribute is handled through the promote component, which is accessed by setting the second argument of an ACV to COMP_PROMOTE. This component is an integer with a Boolean value (0 or 1), which depends on whether an attribute is promoted or not. Built-in EMA model and object attributes are not initially promoted, so their promote components have an initial value of zero (indicating off). Model and object attributes created via the add attribute operator are promoted, however, so their promote components have a value of one (indicating on).

Since the promote component of attributes is separate from and independent of the contents component of attributes, there are several sophisticated combinations of these components. The following table lists the different combinations of the promote component and contents component:

Table 5: Promote and Contents Component Combinations

Promote Component Contents Component Comments
1 <not set> attribute is promoted; contents of attribute represents its default value; the contents is still set to the attribute’s built-in default
1 <set> attribute is promoted; contents of attribute represents its default value; the contents has been set to a user-specified value
0 <not set> attribute is not promoted; contents of attribute represents its true value; the contents is still set to the attribute’s built-in default
0 <set> attribute is not promoted; contents of attribute represents its true value; the contents has been set to a user-specified value

The two ACV forms of the promote component appear below. The value must be an integer pointer for the attr_get operator and an integer for the attr_set operator.

attr_get: <attr_name>, COMP_PROMOTE, &var

attr_set: <attr_name>, COMP_PROMOTE, var

Properties Component

The properties component allows you to get the object ID of the properties object associated with a non-built in EMA attribute. Non-built in attributes include attributes defined in the Process Editor, extended attributes, and attributes appearing on an object through promotion. If the properties component is accessed for a built-in attribute, EMAC_NULL_OBJ_ID will be returned. This get-only component can be accessed by an ACV with the second argument set to the symbolic constant COMP_PROPS.

The ACV form of the properties component appears below. The value must always be an integer pointer.

attr_get: <attr_name>, COMP_PROPS, &var

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com