EMA Operators

Models and objects in EMA can be manipulated by several operators. Operators are implemented as functions callable from C programs; the specific function call syntax is detailed in the next section. This section will introduce the operators in a simplified way. The set of operators known as generic operators can be applied to both models and objects. Each of these have similar semantics for both models and objects. The term for the set of entities to which a generic operator can be applied is M/O, which stands for {Model / Object}. The set of operators known as specific operators can either be applied to a model or an object, but not both. All generic and specific operators are listed in the following table.

Table 3: EMA Operators

Generic Model Specific Object Specific
create read move
destroy write nth
copy code_gen prom_attr_set
print
attr_get
attr_set
attr_add
attr_print

The create operator allocates memory for and initializes a new M/O instance. The initialization process includes setting all M/O attributes to their default contents. The new M/O will be assigned a unique identifier by EMA, which can be used in future calls to operators to reference the M/O. Once created, an M/O will exist until it is either destroyed via the destroy operator, or the EMA-based application program terminates.

The destroy operator deallocates all of the memory used by an M/O instance. The M/O is effectively removed from the EMA environment, and can no longer be manipulated by EMA operators. Attempts to reference destroyed M/O's will result in error conditions. Attributes which reference the destroyed M/O will be searched for by EMA, and it will place these attributes in the “unset” state.

The copy operator creates a new instance of an M/O which is an exact duplicate of an existing M/O instance. All attributes of the original M/O are copied over to the new M/O. The only differences between the original and the duplicate M/O’s are their unique IDs.

The print operator displays the contents of an M/O on the standard output device. Information on each attribute is displayed, including its numeric index, name, type, default value, and current value. EMA-specific information is also printed, such as the number of objects in a model.

The attribute get operator (short form: attr_get) reads the contents of an attribute contained within an M/O instance. The contents of the attribute is unaffected by this operator; it is a non-destructive read operation that is used by an EMA application to inquire about the current state of an M/O. An error condition will result if this operator is applied to attributes that have not been previously set but which have the set-required type modifier. Except for the previous restriction, this operator can be applied to attributes of any core type or type modifier.

The attribute set operator (short form: attr_set) assigns the contents of an attribute contained within an M/O instance. Regardless of the previous contents of the attribute, the contents will be changed to a new value. This operator can be applied to attributes of any core type or type modifier.

The attribute add operator (short form: attr_add) creates a new attribute contained within an M/O instance. The attribute’s name, data type, unit name, and default value are specified. Initially, the new attribute takes on its default value. This operator is used for creating user-defined attributes, and is analogous to the extended attrs. object menu item.

The attribute print operator (short form: attr_print) displays the contents of a single attribute contained within an M/O instance. Displayed information includes its numeric index, name, type, default value, and current value.

The attribute group get operator (short form: attr_group_get) reads the attribute group name of an M/O instance. The attribute group name is used by the object attribute dialog box to organize a large collection of attributes into smaller, manageable sets of attributes called groups. All attributes with the same group name are considered to be part of the same group. The attribute group name is only used by the object attribute dialog box and does not affect any type of analysis. The contents of the attribute are unaffected by this operator; it is a non-destructive read operation that is used by an EMA application to inquire about the current state of an M/O.

The attribute group set operator (short form: attr_group_set) assigns the group name of an M/O instance. Regardless of the previous group name of the attribute, the group name will be changed to a new value.

In addition to the generic operators, there are specific operators that can only be applied to either models or objects, but not both. These include the following:

The read operator can only be applied to models. It opens up an existing model data file stored in a model directory and creates an EMA model that describes the Riverbed model. This operator is the only direct data input mechanism for EMA, and is typically used to read in models that are to be queried or manipulated by an EMA-based application.

The write operator can only be applied to models. It translates an existing EMA model into an equivalent Riverbed model data file in the primary model directory. This operator is the only direct data export mechanism for EMA, and is used to translate the results of an EMA application into a “concrete” model that can be used by Riverbed analysis software.

The code generation operator (short form: code_gen) can only be applied to models. It generates a source code file for an EMA application that describes the EMA model to which it is applied, creating a C code file in the primary model directory (file type suffix .em.c). This operator can be used to obtain a simple “snapshot” application that can regenerate an EMA model that was algorithmically constructed by a much more complex EMA application.

The move operator can only be applied to objects. It takes an existing object located in a particular model, and moves it into another model. The source model will no longer contain the affected object, and any new references to the object will cause an error condition (from the viewpoint of the source model, it is as if the object was destroyed). On the other hand, the destination model has a new object instance which has a unique object ID (the object's previous ID does not in any way correspond to its ID in the destination model).

The Nth operator can only be applied to objects. It takes an index number and returns the unique identifier of the object which corresponds to that index in terms of creation order. The index addresses a counting space that is unique for each type of object; for instance, this operator can obtain the 5th object of type A contained in a model, but not the 5th overall object. This operator is typically used by EMA-based applications to loop through all objects of a particular type. In most models, there are attributes that count the number of objects of each type in the model; these attributes provide the maximum value of the loop counter.

The promoted attribute set operator (short form: prom_attr_set) can only be applied to objects. This operator is similar to attr_set, in that it assigns the contents of an attribute contained within an object. However, the attribute assigned by this operator does not exist before the operator is invoked; prom_attr_set actually creates the attribute anticipating the existence of an attribute with the same name that will be promoted from a lower-level model or object. When an EMA model with promoted attributes is written to a model file and the model is integrated into a simulation, the promoted attribute values will be assigned to corresponding lower-level model or object attributes that have been promoted.