1 External Model Access

Transcription

1 1 External Model Access Function List The EMA package contains the following functions. Ema_Init() on page MFA Ema_Model_Attr_Add() on page MFA Ema_Model_Attr_Get() on page MFA Ema_Model_Attr_Nth() on page MFA Ema_Model_Attr_Print() on page MFA Ema_Model_Attr_Set() on page MFA Ema_Model_Base_Print() on page MFA Ema_Model_Code_Gen() on page MFA Ema_Model_Copy() on page MFA Ema_Model_Create() on page MFA Ema_Model_Destroy() on page MFA Ema_Model_Print() on page MFA Ema_Model_Read() on page MFA Ema_Model_Write() on page MFA Ema_Object_Attr_Add() on page MFA Ema_Object_Attr_Get() on page MFA Ema_Object_Attr_Nth() on page MFA Ema_Object_Attr_Print() on page MFA Ema_Object_Attr_Set() on page MFA Ema_Object_Copy() on page MFA Ema_Object_Create() on page MFA Ema_Object_Destroy() on page MFA Ema_Object_Move() on page MFA Ema_Object_Move_Recursively() on page MFA Ema_Object_Nth() on page MFA Modeler/Release 10.0 MFA-1-1

2 Ema_Object_Print() on page MFA Ema_Object_Prom_Attr_Set() on page MFA Ema_Ov_File_Placement_Mode_Set() on page MFA Package Overview External model access is an OPNET term that is defined as follows: the technique of accessing a model external to the opnet program (i.e., without using the services provided by the OPNET graphical editors). In this context, the definition of accessing a model includes creating it, modifying it, and extracting data from it. External model access is supported via a library of C and C++ accessible functions that serve as a programmatic specification and query language. This library is named the External Model Access (Ema) package, and it can be viewed as an Application Program Interface (API) for creating and extracting data from OPNET model files. Note To use External Model Access in Windows, make sure that <reldir>/sys/pc_intel_win32/bin is the first directory listed in your PATH environment. External model access is provided to adequately support a number of special requirements: Large models, involving many objects and interconnections, can be tedious to enter using the graphical editors, and it is easy to make errors of omission when specifying attribute values. If large models have a regular structure (such as a ring, grid, tree, etc.), they are especially conducive to algorithmic specification using a programmatic interface. Many applications of OPNET involve model construction based on sets of parameters associated with real-world equipment configurations. Often, the parameter sets are conveniently stored in an on-line database. In these situations, it is useful to have an automated model construction process, especially if the number of models to be built is large or open-ended. Automated model construction is possible with a programmatic specification language. Supporting an API for OPNET model files allows user-written programs to open and query models, thus providing an open interface. This can be very useful when exporting OPNET model data to other applications. EMA function calls are designed to be external in C or C++ programs developed by users. The ability to embed EMA in C or C++ is superior to a stand-alone language, since it allows all the flexibility of a common, full-capability procedural language to be applied to the task of creating models. Model-creating programs can have a wide range of complexities: on the simple end, a linear sequence of calls to EMA primitives can be prepared to create a single model; this is MFA-1-2 Modeler/Release 10.0

3 equivalent to an editing session with an OPNET graphical editor. On the sophisticated end, an interactive program can be developed that creates models according to a variety of dynamic inputs, including user prompts or third-party database queries. The diagram on the next page depicts a sophisticated application that interfaces to an external database via a query language, and to OPNET via the Ema package. Figure 1-1 Example Database-Driven Model Building Application Database Interface Application Third-Party Relational Database Embedded Relational Query Language External Model Access (EMA) Calls OPNET Models To support the convenient embedding of EMA statements in C/C++ programs, EMA statements are implemented as C/C++ function calls. The Ema package is an external object code library which must be linked in with application programs that make calls to it. The function call interface allows an EMA statement to be made from within almost any C/C++ control structure, such as IF-THEN-ELSE clauses, and for, while, and do-while loops. Within EMA, OPNET model attributes are described and accessed in a standard, object-based methodology. This drastically reduces the number of functions that must be learned to specify models, and it allows application programs that process models to be written in a generic, model independent style. For instance, a simple EMA program can be written to print out the complete contents of a model using the same algorithm, regardless of the model type. Modeler/Release 10.0 MFA-1-3

4 Figure 1-2 shows the model types that can be read and written with EMA: Figure 1-2 EMA-Supported Model Types Primary Modeling Domain Types project model network model node model link model path model demand model traffic model derived node model derived link model derived path model derived demand model process model public attribute description external system description Parameter Types probability density function packet format ICI format cartographic data set Simulation Types probe list web report probe list SLA report probe list simulation sequence output vector output scalar EMA Concepts The Ema package is an API that incorporates several principles of object-based design, such as: data hiding: the user of EMA is not exposed to the internal physical, byte-by-byte structure of an OPNET model. Instead, access to the various model components is provided via a set of functions that shield detail and verify the integrity of model access. generic operators: a small set of generic operators can be applied to any object managed by EMA. These operators include the ability to create and destroy objects, to set or get their components, and to copy or move them. In addition, all objects have a set of generic attributes that EMA maintains. The remainder of this section will present definitions of the major concepts of EMA, each accompanied by a diagram that depicts the concept. Note that EMA concepts tend to have familiar names, such as object, but that they do have very specific semantics within EMA that may vary from the familiar usage of the terms. MFA-1-4 Modeler/Release 10.0

5 Model Models in EMA correspond to models in OPNET, as presented in Figure 1-2. However, EMA models are not identical to OPNET models. Within EMA, a model is a collection of data that specifies an OPNET model. In other words, while an application program is using EMA to operate on a model, it is actually building up a set of data that will later be used by EMA to construct an OPNET model. During the EMA session, the rules of what can be done with the model and how it is internally stored and manipulated are all governed strictly by EMA. As soon as the model is written out by EMA, however, a corresponding OPNET model is generated, and it can then be manipulated by all of the existing tools in OPNET which deal with models (such as graphical editors, op_mko, and op_mksim). Figure 1-3 EMA Application Model File Operations process virtual memory of EMA application EMA model read operation write operation OPNET model data file Models in EMA are sets of objects, each of which has an object type. As concrete examples, one of the objects that can be created in a network model is a node, and one of the objects that can be created in a node model is a processor. For flexibility, arbitrary quantities of objects of various types can be created within a model; the maximum number is only limited by the amount of virtual memory available to the program that is making calls to EMA. Figure 1-4 Objects Within EMA Model object EMA Model object object object object object object As with objects, there can be multiple models present at the same time in an EMA application. The maximum number of models present at any one time in an EMA application is limited by the amount of available virtual memory. Modeler/Release 10.0 MFA-1-5

6 Figure 1-5 Models Within EMA Application Memory process virtual memory of EMA application EMA model EMA model EMA model EMA model EMA model Models are distinguished from one another in two ways: by type and by instance. Each model instance has a unique identifier that distinguishes it from all other models: this is known as the model ID. In addition, model instances that are of similar type share a common model type (for instance, all network models are identified as being of network type). One of these two identifiers must be passed to most EMA calls, since EMA has to know which model or model type is being referenced. The C/C++ language type definitions and typical function argument names for these identifiers are listed below (the type definitions are provided for code documentation and clarity; these identifiers are in fact just integers, and may be handled the same way as any regular integer in C/C++). Table 1-1 Ema Model Data Types C/C++ Type Definition EmaT_Model_Type EmaT_Model_Id Typical Argument Name model_type model_id End of Table 1-1 Object Objects in EMA describe components within an OPNET model. For each model component that can be created using the opnet program, there is a corresponding EMA object that describes it (examples of such components are fixed nodes, processor modules, and process model states). The description of an OPNET model component does not cover its internal structure or its procedural behavior. Instead, the description covers its parameterization. For example, the description of a processor might include attributes that govern its generation of packets over time, such as the interarrival PDF being utilized. MFA-1-6 Modeler/Release 10.0

7 An EMA object is essentially a set of attributes, each of which contains a value. All attributes of an OPNET model component are supported by the corresponding EMA object. The initial set of object attributes, and the default values of each of these attributes, are determined by the type of object (the Ema package contains an internal database of all object attributes and default values). However, the attribute set can be extended by the user, using an EMA function call that corresponds to the extended attrs button within OPNET. Figure 1-6 Ema Model Data Types Object Type #1 Object Type #2 object attribute attribute attribute attribute attribute object attribute attribute attribute Similar to models, objects are distinguished by type and by instance. Each object instance in a model has a unique identifier which distinguishes it from all other objects within the model: this is known as the object ID (note that object IDs are not unique across models, so model #0 and model #1 can both have an object #45). Therefore, the specification of a unique object instance in an EMA application must also include the ID of the model in which the object is contained. Object instances which are of similar type share a common object type (for instance, all processor objects are identified as being of processor type). The C/C++ language type definitions and typical function call argument names for these identifiers are listed below (the type definitions are provided for code documentation and clarity; these identifiers are in fact just integers, and may be handled the same way as any normal integer in C/C++). Table 1-2 EMA Object Data Types C/C++ Type Definition EmaT_Object_Type EmaT_Object_Id Typical Argument Name object_type object_id End of Table 1-2 Attribute The EMA concepts introduced so far (model and object) are essentially grouping elements. They don't directly contain data that describes OPNET model components; what they do contain directly are attributes (the previous section explained that objects contain sets of attributes, but models also contain sets of attributes, in cases where model-wide parameters must be described). Attributes actually hold the data that parameterizes OPNET model components. Modeler/Release 10.0 MFA-1-7

8 The data stored in each attribute is known as the attribute's contents. The contents of an attribute can be assigned to the attribute or read from the attribute using the appropriate EMA operators, to be described in later sections. The diagram below shows an object with several attributes; each attribute has an integer as its contents. Figure 1-7 Object Attribute Structure object attribute names A B 88 0 attribute contents C 21 D 1 F 98 Because modeling and analysis entities are typically parameterized using a variety of data types, attributes must also be of different types (e.g., integer, ). The core types of attributes are integer double textlist object ID double vector poly The integer, double (i.e., double-precision floating point) and attribute types are similar to the C data types on which these are based. The four special attribute types are textlist, object ID, double vector, and poly. These data types provided enhanced, direct support for describing components of OPNET models. A textlist is a collection of s that form an ordered list. Textlists are implemented by a C data structure, and are indirectly manipulated by a set of functions within the Program Library (Prg) package. Textlist attributes accept textlists as values; an example of a textlist attribute is the list of enter executives associated with a process model state. MFA-1-8 Modeler/Release 10.0

9 The Prg package (in which function names have the form prg_) is distinct from the Simulation Kernel s Programming package (in which function names have the form op_prg_). Prg package functions can be called by EMA programs, external tool programs, and process model code. The Simulation Kernel Programming package functions can be called only by process model code. The object ID type, as introduced earlier, is really an integer. However, it has special semantics associated with it, in that its contents references another object in the model. The referenced object must exist for this attribute to have valid contents. An object ID attribute can only reference an object in the same model as the object that contains the attribute; it cannot reference objects in other models. The presence of object ID attributes allows models to become directed graphs of inter-referencing objects, as depicted in the following figure. Figure 1-8 Interobject References model A B C object object A C 55 X Y object B 44 object X 7 Y 7 A double vector is an attribute that contains a sequence of real numbers that represent a single parameter of an object or model. The vector stores a sequence of double-precision floating-point values in an efficient format, with consecutive elements packed into consecutive locations of memory (this is similar to an array in the C language). Each element of a double vector has an index, which is used to access it (elements are indexed starting with 0). Each double vector attribute has a default size that is built into EMA s internal database of objects and models. The default size can be changed through a special EMA operator, to extend or shrink the vector. A poly type is an attribute that can take on a variety of values. The value of a poly attribute is one of the allowed attribute types described in this section, except for poly itself. In addition to the attribute core types, there is a set of attribute type modifiers, which are layered on top of the core type. These modifiers primarily affect the ways in which the attribute is accessed through EMA. Modeler/Release 10.0 MFA-1-9

10 The attribute type modifiers are array toggle set-required The array modifier expands an attribute to actually represent a series of attributes, each identified by a unique array index. The concept is somewhat like an array in C, in which a series of elements are referenced by index. However, attribute arrays are actually implemented with dynamically allocated memory, so they have the advantage that they can grow to arbitrary size. The toggle modifier defines an attribute as having two states: enabled and disabled. Regardless of the state of the attribute, however, the attribute still has a defined contents. Toggles are useful for OPNET objects that have optional behaviors that require parameters if enabled. For example, processor modules by default are not regularly interrupted, so the interrupt rate parameter is irrelevant. When regular interrupts are enabled, however, the interrupt rate parameter is meaningful. This sort of object behavior could have been described by two attributes, one of which contains the interrupt rate, and another which serves as a Boolean indicating whether or not regular interrupts are enabled. However, it is more convenient to combine the two pieces of data into a single attribute using the toggle modifier. The set-required modifier indicates that an attribute has no default value, and that it must have an assigned contents (i.e., it must be set ) before a model can be written out to disk. This modifier is mostly used for attributes which have object ID as their core type, since if such an attribute is not set, there is no intelligent or obvious default value. Each attribute that is supported is presented in EMA Built-In Attributes on page MFA The core type and type modifiers for each attribute are also listed in that section. 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 MFA-1-10 Modeler/Release 10.0

11 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 appear in Figure 1-3. Table 1-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 End of Table 1-3 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. Modeler/Release 10.0 MFA-1-11

12 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 in OPNET. 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. 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 OPNET model data file stored in a model directory, and creates an EMA model that describes the OPNET 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 OPNET 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 in the OPNET system. 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. MFA-1-12 Modeler/Release 10.0

13 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 OPNET model or object. When an EMA model with promoted attributes is written to an OPNET 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. 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 Modeler/Release 10.0 MFA-1-13

14 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> MFA-1-14 Modeler/Release 10.0

15 Depending on the core type of the attribute, the variable used as the value of the ACV should be declared and passed differently, as shown in Table 1-4. 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 ( ), or ( constant )); all of the argument conventions of the C language will apply. Table 1-4 COMP_CONTENTS Value Types Core Type Value Declaration Operator ACV Form integer int var; attr_get attr_set double double var; attr_get attr_set char var [256]; attr_get attr_set textlist PrgT_List *var; attr_get attr_set object ID EmaT_Object_Id var; attr_get attr_set A, C, &var A, C, var A, C, &var A, C, var A, C, var A, C, var A, C, &var A, C, var A, C, &var A, C, var End of Table 1-4 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 given in Table 1-4 still apply to this component. Modeler/Release 10.0 MFA-1-15

16 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 (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. Double Vector Contents Component <attr_name>, COMP_ARRAY_SIZE, &var 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> MFA-1-16 Modeler/Release 10.0

17 Despite the modified form of the ACVs middle argument, the value types for the COMP_CONTENTS component given in Table 1-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 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> Modeler/Release 10.0 MFA-1-17

18 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. Object Type Component The ACV form of the set component appears below. The value must always be an integer pointer. <attr_name>, COMP_SET, &var EMA supports several built-in attributes for models (described in EMA Built-In Attributes on page MFA-1-21). 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. MFA-1-18 Modeler/Release 10.0

19 Promote Component 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 The environment architecture of OPNET 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. Within OPNET, 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. As in OPNET, built-in 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). Modeler/Release 10.0 MFA-1-19

20 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. Table 1-5 illustrates the different combinations of the promote component and contents component: Table 1-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 End of Table 1-5 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 MFA-1-20 Modeler/Release 10.0

21 EMA Built-In Attributes To facilitate the general manipulation of models and objects, several attributes have been built into the Ema package that can be accessed for generic models or objects, regardless of type. There are currently four such built-in attributes, and they are all get-only, since they are queries about model or object data. Each is described below. ATTR_EMA_TYPE This attribute is supported for both models and objects. It provides a means of determining the type of a model or object when this data is unknown. For instance, if an object ID is passed to a function that will perform different actions depending on the object type, the object type can be obtained using this attribute. The only component supported by this attribute is COMP_CONTENTS. ATTR_EMA_INDEX This attribute is only supported for objects. It provides a means of determining the index of an object in the set of all objects of the same type within a model. For instance, if object E is the third object of its type to be created, then this attribute will take on the value 2 (object indices start at zero). The only component supported by this attribute is COMP_CONTENTS. ATTR_EMA_NUM_ATTRS This attribute is supported for both models and objects. It provides a means of determining the number of attributes contained within a specified model or object. This quantity can be useful in procedures that will loop through all attributes of a model or object and perform some operation on each one (such as printing their contents). The only component supported by this attribute is COMP_CONTENTS. ATTR_EMA_NUM_OBJECTS This attribute is supported for models. It provides a means of determining the number of objects of a particular type that are contained in a model. This quantity is useful when looping through all the objects in a model with a particular type. This attribute is used in conjunction with the COMP_OBTYPE component. EMA Base Objects A base set of objects is defined in the Ema package to support more complex objects. These base objects are described below and are used by OPNET-specific objects described in following sections. Modeler/Release 10.0 MFA-1-21

22 Symbol Object The symbol object represents the mapping of a value to a symbolic name. Symbol object IDs are used by the symbol map list attribute of the properties object. Table 1-6 Symbol Object Attributes symbol (empty) value poly 1 End of Table value type determined at run time Properties Object When a user-defined attribute is added to a model or object, the object identifier of a properties object is a required argument. The properties object (Table 1-7) contains information about the added attribute s name, type, symbol map, and other properties. Table 1-7 Properties Object Attributes (Part 1 of 2) public name (empty) units (empty) default value poly 1 comments high limit low limit textlist double double symbol map list array of object IDs 2 flags integer 3 data type integer 4 count properties object ID 5 handler library 6 (empty) click handler 6 (empty) confirm handler 6 (empty) MFA-1-22 Modeler/Release 10.0

23 Table 1-7 Properties Object Attributes (Part 2 of 2) new value handler 6 (empty) display handler 6 (empty) list attribute definitions array of object IDs 7 End of Table value type determined at run time and must correspond to the type specified by the data type attribute 2. object IDs of symbol objects 3. valid types are described in Table Properties Object Flags Symbolic Constants on page MFA valid types are EMAC_INTEGER, EMAC_DOUBLE, EMAC_STRING, EMAC_TOGGLE, EMAC_TOGGLE_DOUBLE, EMAC_COMPOUND, or EMAC_DATAFILE 5. object ID of properties object (only if data type is EMAC_COMPOUND) defining the properties of the count attribute of a compound object 6. These attributes indicate custom event-handler routines to override the standard interface for setting object attributes. 7. object IDs of attribute definition objects of sub-objects (only if data type is EMAC_COMPOUND) defining the properties of each attribute of a compound object s sub-object Attribute Definition Object An attribute definition maps an attribute name to its properties. Attribute definitions are used in the properties object to define the properties of a compound attribute s sub-object attributes. In that context, the properties of each sub-object of a compound attribute contain a list of attribute definition objects. Each attribute definition object provides an attribute name, group, and its corresponding properties. Table 1-8 Attribute Definition Object Attributes name (empty) group (empty) properties object ID 1 End of Table object ID of properties object Modeler/Release 10.0 MFA-1-23

24 Compound Value Object When an attribute has a type EMAC_COMPOUND, its value is the object ID of a compound value object. The compound value object contains two attributes. The list attribute is an array of object IDs, each ID identifies a compound object (described below) which is a sub-object of the compound value. The count attribute specifies explicitly how many compound objects are part of the compound value. Table 1-9 Compound Value Object Attributes count integer list array of object IDs 1 (empty) End of Table object IDs of compound objects Compound Object Compound objects are objects which contain no initial attributes. All of the attributes in compound objects are explicitly added with calls to the Ema_Object_Prom_Attr_Set() function. Compound objects represent the sub-objects of compound attribute value objects. Examples of Compound Value Object Usage This section provides an example (through C code fragments) of how EMA functions are used to construct EMA compound value objects. The compound attribute structure shown in the figure below will be constructed through EMA. Figure 1-9 Compound Value Object list subobject0 count: 2 attr0: 1.0 attr1: 2.2 attr0: 11.0 attr1: 12.2 subobject1 The first step in specifying a compound value object is allocating the object itself: comp_val_objid = Ema_Object_Create (model_id, OBJ_ATTR_COMP_VALUE); Next, the individual compound objects, or sub-objects, need to be allocated and set: subobject0_objid = Ema_Object_Create (model_id, OBJ_ATTR_COMP_OBJ); subobject1_objid = Ema_Object_Create (model_id, OBJ_ATTR_COMP_OBJ); MFA-1-24 Modeler/Release 10.0

25 Each sub-object next gets the attributes that it needs added on. This is a two-step process, however, because new attributes added to an object require a properties object. Therefore, properties objects are created first: attr0_props_objid = Ema_Object_Create (model_id, OBJ_ATTR_PROPS); attr1_props_objid = Ema_Object_Create (model_id, OBJ_ATTR_PROPS); The properties objects need to have values for their attributes specified: prg_lptr = prg_list_create (); Ema_Object_Attr_Set (model_id, attr0_props_objid, "units", COMP_CONTENTS, "", "default value", COMP_CONTENTS_TYPE, EMAC_DOUBLE, "default value", COMP_CONTENTS, (double) 0, "comments", COMP_CONTENTS, prg_lptr, "high limit", COMP_CONTENTS, 0.0, "low limit", COMP_CONTENTS, 0.0, "symbol map list", COMP_INTENDED, EMAC_DISABLED, "flags", COMP_CONTENTS, EMAC_DEFC_AUTOASSIGN, "data type", COMP_CONTENTS, 1, "count properties", COMP_INTENDED, EMAC_DISABLED, "list attribute definitions", COMP_INTENDED, EMAC_DISABLED, EMAC_EOL); (A similar call for attr1_props_objid is not shown here.) Next, with the properties of sub-object attributes ready, the attributes are added to each sub-object: Ema_Object_Prom_Attr_Set (model_id, subobject0_objid, "attr0", attr0_props_objid); Ema_Object_Prom_Attr_Set (model_id, subobject0_objid, "attr1", attr1_props_objid); Ema_Object_Prom_Attr_Set (model_id, subobject1_objid, "attr0", attr0_props_objid); Ema_Object_Prom_Attr_Set (model_id, subobject1_objid, "attr1", attr1_props_objid); Values for the attributes on the sub-objects can now be provided: Ema_Object_Attr_Set (model_id, subobject0_objid, "attr0", COMP_CONTENTS, 1.0, "attr1", COMP_CONTENTS, 2.2, EMAC_EOL); Ema_Object_Attr_Set (model_id, subobject1_objid, "attr0", COMP_CONTENTS, 11.0, "attr1", COMP_CONTENTS, 12.2, EMAC_EOL); Finally, the compound value object s list and count attributes are set to include the sub-objects that have been created and defined: Ema_Object_Attr_Set (model_id, comp_val_objid, "count", COMP_CONTENTS, 2, "list", COMP_ARRAY_CONTENTS(0), subobject0_objid, "list", COMP_ARRAY_CONTENTS(1), subobject1_objid, EMAC_EOL); Modeler/Release 10.0 MFA-1-25

26 Working with Symbol Maps Building upon the previous example, symbol objects are introduced and used in setting a sub-object s attribute value. In the following example, a symbol object will be created mapping the One to the value 1.0. The properties object corresponding to attr0 is then modified to include the symbol object in its symbol map. Finally, the symbol is set as a value within subobject1. First, the symbol object is created: symbol_objid = Ema_Object_Create (model_id, OBJ_ATTR_SYMMAP); The mapping from One to 1.0 is specified in the symbol object s attributes: Ema_Object_Attr_Set (model_id, symbol_objid, "symbol", COMP_CONTENTS, "One", "value", COMP_CONTENTS_TYPE, EMAC_DOUBLE, "value", COMP_CONTENTS, 1.0, EMAC_EOL); In the preceding code, note that, because the value attribute of a symbol object is of type poly, COMP_CONTENTS_TYPE is used to make the type of the value actually being set on the attribute explicit. The properties object for attr0 is modified to include the symbol object: Ema_Object_Attr_Set (model_id, attr0_props_objid, "symbol map list", COMP_ARRAY_CONTENTS(0), symbol_objid, EMAC_EOL); Finally, the value of attr0 of subobject1 is set to a symbolic value. The code pertaining to the creation of the compound value object did not have to be modified: Ema_Object_Attr_Set (model_id, subobject1_objid, "attr0", COMP_CONTENTS_SYMBOL, "One", EMAC_EOL); Models, Objects, and Attributes This section documents all OPNET models, objects, and attributes that are currently supported via the Ema package. Models, objects, and attributes each have a unique symbolic constant (or ) that identifies them in calls to the EMA functions documented in the previous section. The sets of symbolic constants and s are listed in tables within this section. For attributes, the core types and type modifiers are also listed. MFA-1-26 Modeler/Release 10.0

27 Some of the objects and attributes have names that may be unfamiliar to users of the OPNET program, because they represent data that is transparently managed by the interactive tools of OPNET. For instance, most of the models have a position object which is used to specify the position on the screen where an icon or other graphical item should be drawn. This data is not explicitly entered by the user within OPNET, since it is captured implicitly via the position of the mouse. However, in an EMA-based application, the data must be explicitly referenced and assigned. In addition, some object types have redundant attributes. These are attributes that provide compatibility across various releases of OPNET. There are two kinds of redundant attributes: An attribute that appears on more than one object type. Multiple attributes that appear on the same object type and specify the same information. Redundant attributes allow an EMA application developed under one OPNET release to be used with another release when Ema_Init() is called with the EMAC_MODE_REL_<nn> flag, as described in Ema_Init() on page MFA For example, the subnet object has some redundant attributes (such as grid style) that belong to and are described with the subnet view object in the current release, but which belonged to the subnet object in an earlier release. Redundant attributes may become visible when you generate EMA code and can be accessed by functions such as Ema_Object_Print() and Ema_Model_Attr_Get(). However, only attributes that correspond to the release specified by the EMAC_MODE_REL_<nn> flag have actual values that are updated as the model runs. Symbolic Constants Table 1-10 lists the symbolic constants that identify each OPNET model type supported by EMA. Table 1-10 OPNET Models (Part 1 of 2) Model Type project model network model node model process model external system definition link model Symbolic Constant MOD_PROJECT MOD_NETWORK MOD_NODE MOD_PROCESS MOD_ESD MOD_LINK Modeler/Release 10.0 MFA-1-27

28 Table 1-10 OPNET Models (Part 2 of 2) Model Type path model demand model traffic model PDF packet format ICI format probe list web report probe list SLA report probe list simulation sequence output vector output scalar cartographic data set public attribute description model derived node model derived link model derived path model derived demand model Symbolic Constant MOD_PATH MOD_DEMAND MOD_TRAFFIC MOD_PDF MOD_PK_FORMAT MOD_ICI_FORMAT MOD_PROBES MOD_REPORT_PROBES MOD_SLA_PROBES MOD_SIM_SEQ MOD_OUTVECTORS MOD_OUTSCALARS MOD_CARTO MOD_PUB_AD MOD_DER_NODE MOD_DER_LINK MOD_DER_PATH MOD_DER_DEMAND End of Table 1-10 MFA-1-28 Modeler/Release 10.0

29 Table 1-11 lists symbolic constants that appear as special values in the attribute tables forming the remainder of this section. Table 1-11 Special Attribute Values Meaning disabled toggle enabled toggle "infinite" double-precision value unassigned object ID Symbolic Constant EMAC_DISABLED EMAC_ENABLED EMAC_DBL_INFINITY EMAC_NULL_OBJ_ID End of Table 1-11 Modeler/Release 10.0 MFA-1-29

30 Project Model Table 1-12 Project Objects Object Type scenario scenario import state traffic growth data Symbolic Constant OBJ_PJ_SCENARIO OBJ_PJ_SCENARIO_IMPORT_STATE OBJ_PJ_SCENARIO_LONG_TERM_STUDY End of Table 1-12 Table 1-13 Project Model Attributes name "unnamed" current scenario integer 0 End of Table 1-13 Table 1-14 Scenario Object Attributes name "unnamed" import state object ID 1 long term study object ID 2 End of Table ID of scenario import state object. 2. ID of traffic growth object Table 1-15 Scenario Import State Object Attributes (Part 1 of 2) server name "localhost" subnet name aggregation integer 0 repair flag toggle EMAC_ENABLED icons flag toggle EMAC_DISABLED max per hub flag toggle EMAC_DISABLED MFA-1-30 Modeler/Release 10.0

31 Table 1-15 Scenario Import State Object Attributes (Part 2 of 2) max per switch flag toggle EMAC_DISABLED max per hub integer 0 max per switch integer 0 End of Table 1-15 Table 1-16 Traffic Growth Object Attributes number of simulations integer 1 time units integer 1 OPC_PJ_TIME_UNITS_SECONDS time between simulations double 1.0 start time start date result storage method integer 2 OPC_PJ_RESULT_STORE_EACH_SIMULATION import options integer 3 OPC_PJ_IMPORT_NOTHING growth method integer 4 OPC_PJ_GROWTH_REGULAR_SIMPLE growth rate double 10.0 growth table double vector End of Table symbolic constant values for this attribute appear in Table Project Traffic Growth Result Storage Method Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Project Traffic Growth Result Storage Method Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Project Traffic Growth Import Options Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Project Traffic Growth Method Symbolic Constants on page MFA Modeler/Release 10.0 MFA-1-31

32 Network Model Table 1-17 Network Objects Object Type position interface description attribute assignment fixed subnet fixed node simplex point-to-point link duplex point-to-point link bus link bus tap path demand subnet view shape annotation text annotation line annotation Symbolic Constant OBJ_NT_POS OBJ_NT_INTF_DESC OBJ_NT_ATTR_ASSGN OBJ_NT_SUBNET_FIX OBJ_NT_NODE_FIXED OBJ_NT_PTSIMP_LINK OBJ_NT_PTDUP_LINK OBJ_NT_BU_LINK OBJ_NT_TAP OBJ_NT_PATH OBJ_NT_DEMAND OBJ_NT_SUBNET_VIEW OBJ_NT_ANNOT_SHAPE OBJ_NT_ANNOT_TEXT OBJ_NT_ANNOT_LINE End of Table 1-17 Table 1-18 Network Model Attributes ext fileset textlist 1 keywords list textlist view subnet object ID 2 tmm propagation models array of object IDs 3 iso elev map color levels array of object IDs 4 iso elev map label color integer 1 End of Table 1-18 MFA-1-32 Modeler/Release 10.0

33 1. Names of external object files. 2. object ID of object that represents the subnet currently in view. 3. object IDs of type Nt_Tmm_Propagation_Model_Config. 4. object IDs of type Nt_Iso_Elev_Map_Color_Settings. Modeler/Release 10.0 MFA-1-33

34 Table 1-19 Position Object Attributes x y set-required double set-required double End of Table 1-19 Table 1-20 Interface Description Object Attributes promotion name set-required 1 merged names set-required textlist 2 flags integer 3 0 properties object ID 4 suppressed symbols textlist 5 type integer 6 (empty) -1 End of Table New name of attribute if a rename/merge is being represented; original attribute name otherwise. 2. List of pre-rename attribute names if a rename/merge is being represented; original attribute name otherwise. 3. A combination of some of the following: OPC_ID_INHRT_LIMS, OPC_ID_INHRT_VAL_RESTRICT, OPC_ID_INHRT_COMMENTS, OPC_ID_INHRT_DEFVAL, and OPC_ID_INHRT_UNITS. 4. object ID of properties object. 5. textlist containing names of suppressed symbols. 6. valid types are EMAC_INTEGER, EMAC_DOUBLE, EMAC_STRING, EMAC_TOGGLE, EMAC_TOGGLE_DOUBLE, EMAC_COMPOUND, or EMAC_DATAFILE. Table 1-21 Attribute Assignment Object Attributes name operation integer 1 value poly 2 type integer 3-1 End of Table Assignment operation constant (one of OPC_AA_IGNORE, OPC_AA_SET, or OPC_AA_SUPPRESS). MFA-1-34 Modeler/Release 10.0

35 2. value type determined at run time and must correspond to the type specified by the type attribute. 3. valid types are EMAC_INTEGER, EMAC_DOUBLE, EMAC_STRING, EMAC_TOGGLE, EMAC_TOGGLE_DOUBLE, EMAC_COMPOUND, or EMAC_DATAFILE. Modeler/Release 10.0 MFA-1-35

36 Table 1-22 Fixed Subnet Object Attributes Name Alias Type Default attribute promotion toggle Enabled name set-required priority integer 0 user id integer 0 x position longitude double 0.0 (subnet grid unit) y position latitude double 0.0 (subnet grid unit) x span double 1.0 (subnet grid unit) y span double 1.0 (subnet grid unit) threshold double 0.0 (pixels/s.g.u.) map "NONE" icon name icon 1 outline color integer 2 grid unit integer 3 fixed subnet OPC_GFX_COLOR_RGB003 OPC_GRID_UNIT_NONE subnet object ID 4 view stack object ID 5 doc file nt_subnet_fix iso-elev-map list iso-elev-map line threshold textlist double 0.0 End of Table name of icon in an icon database. 2. symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Grid Unit Symbolic Constants on page MFA object ID of surrounding subnet object; set to EMAC_NULL_OBJ_ID if no surrounding subnet (i.e., object is top-level subnet with name attribute set to "top"). 5. object IDs of subnet view objects. MFA-1-36 Modeler/Release 10.0

37 Table 1-23 Fixed Node Object Attributes Name Alias Type Default name set-required model set-required 1 user id integer 0 x position double 0.0 (subnet grid unit) y position double 0.0 (subnet grid unit) altitude double 0.0 (subnet grid unit) priority integer 0 condition toggle EMAC_ENABLED threshold double 0.0 (pixels/s.g.u.) icon name icon "fixed_comm" subnet set-required object ID 2 doc file "nt_node" alias array of s tooltip "" End of Table name of node model, without suffix. 2. object ID of surrounding subnet object. Table 1-24 Simplex Point-to-Point Link Object Attributes (Part 1 of 2) Name Alias Type Default name model 1 "pt_base" channel count integer 1 transmitter source tx 2 receiver dest rx 2 data rate double packet formats textlist 3 OPC_NT_LINK_ALLPKS Modeler/Release 10.0 MFA-1-37

38 Table 1-24 Simplex Point-to-Point Link Object Attributes (Part 2 of 2) Name Alias Type Default delay double 0.0 (sec) ber double 0.0 (err/bit) condition toggle EMAC_ENABLED user id integer 0 cost double 0.0 txdel model 4 "dpt_txdel" propdel model d "dpt_propdel" error model d "dpt_error" ecc model d "dpt_ecc" source site source node set-required object ID 5 dest site dest node set-required object ID e path array of object IDs 6 color gfx color integer 7 OPC_GFX_COLOR_RGB233 subnet object ID 8 doc file "nt_link" tooltip "" End of Table name of node model, without suffix. 2. hierarchical name of connected point-to-point transceiver; formatted as: [<subnet_ name(s)>.]<node_name>.<module_name> Dot-separated subnet names only appear in the hierarchical name if the link is directly connected to a subnet containing the transceiver; otherwise the hierarchical name only consists of node and module names. 3. textlist containing names of packet formats this link can transmit. 4. name of Transceiver Pipeline Stage object code file, without suffix. 5. object ID of directly connected subnet or fixed node object. 6. object IDs of position objects that define link path. 7. symbolic constant values for this attribute appear in the Table Graphics Color Symbolic Constants on page MFA object ID of surrounding subnet object. MFA-1-38 Modeler/Release 10.0

39 Table 1-25 Duplex Point-to-Point Link Object Attributes (Part 1 of 2) Name Alias Type Default name model 1 "pt_base" channel count integer 1 transmitter a 2 transmitter b receiver a receiver b b data rate double packet formats textlist 3 OPC_NT_LINK_ALLPKS delay double 0.0 (sec) ber double 0.0 (err/bit) condition toggle EMAC_ENABLED user id integer 0 cost double 0.0 txdel model 4 "dbu_txdel" propdel model d "dbu_propdel" error model d "dpt_error" ecc model d "dpt_ecc" site a set-required object ID 5 site b set-required object ID e path array of object IDs 6 color gfx color integer 7 OPC_GFX_COLOR_WHITE Modeler/Release 10.0 MFA-1-39

40 Table 1-25 Duplex Point-to-Point Link Object Attributes (Part 2 of 2) Name Alias Type Default subnet object ID 8 doc file "nt_link" tooltip "" End of Table name of node model, without suffix. 2. hierarchical name of connected point-to-point transceiver; formatted as: [<subnet_ name(s)>.]<node_name>.<module_name> Dot-separated subnet names only appear in the hierarchical name if the link is directly connected to a subnet containing the transceiver; otherwise the hierarchical name only consists of node and module names. 3. textlist containing names of packet formats this link can transmit. 4. name of Transceiver Pipeline Stage object code file, without suffix. 5. object ID of directly connected subnet or fixed node object. 6. object IDs of position objects that define link path. 7. symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA object ID of surrounding subnet object. MFA-1-40 Modeler/Release 10.0

41 Table 1-26 Bus Link Object Attributes name model 1 "bu_adv" channel count integer 1 data rate double packet formats textlist 2 (empty) delay double 0.0 (sec/m) ber double 0.0 (err/bit) condition toggle EMAC_ENABLED user id integer 0 cost double 0.0 txdel model 3 "dbu_txdel" closure model c "dbu_closure" propdel model c "dbu_propdel" coll model c "dbu_coll" error model c "dbu_error" ecc model c "dbu_ecc" color integer 4 OPC_GFX_COLOR_RGB023 subnet set-required object ID 5 path array of object IDs 6 doc file "nt_bus" tooltip " " End of Table name of node model, without suffix. 2. textlist containing names of packet formats this link can transmit. 3. name of Transceiver Pipeline Stage stage model, without suffix. 4. symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA object ID of surrounding subnet object. 6. object IDs of position objects that define link path. Modeler/Release 10.0 MFA-1-41

42 Table 1-27 Bus Tap Object Attributes Name Alias Type Default name model 1 "tp_adv" transmitter source tx 2 receiver dest rx b condition toggle EMAC_ENABLED user id integer 0 cost double 0.0 color gfx color integer 3 OPC_GFX_COLOR_GREY site node set-required object ID 4 path array of object IDs 5 bus object ID 6 subnet object ID 7 doc file "nt_bus_tap" tooltip "" End of Table name of node model, without suffix. 2. hierarchical name of connected bus transceiver; formatted as: [<subnet_ name(s)>.]<node_name>.<module_name> Dot-separated subnet names only appear in the hierarchical name if the link is directly connected to a subnet containing the transceiver; otherwise the hierarchical name only consists of node and module names. 3. symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA object ID of directly connected subnet or fixed node object. 5. object IDs of position objects that define tap path. 6. object ID of directly connected bus link object. 7. object ID of surrounding subnet object. MFA-1-42 Modeler/Release 10.0

43 Table 1-28 Subnet View Object Attributes min x double min y double 90.0 sbar x double 0.0 sbar y double 0.0 grid step double 15.0 resolution double 2.5 grid style integer OPC_GRID_STYLE_NONE grid color integer OPC_GFX_COLOR_RGB111 End of Table 1-28 Table 1-29 Shape Annotation Attributes name NULL shape integer 0 fill toggle EMAC_DISABLED color color RED x position double 0.0 y position double 0.0 width double 0.0 height double 0.0 subnet object ID 1 End of Table object ID of surrounding subnet object. Modeler/Release 10.0 MFA-1-43

44 Table 1-30 Line Annotation Attributes name NULL color color BLUE drawing style integer 0 line style integer 0 head arrow toggle EMAC_DISABLED tail arrow toggle EMAC_DISABLED thickness double 1.0 path array of object IDs 1 subnet object ID 2 End of Table object IDs of position objects that define line path. 2. object ID of surrounding subnet object. Table 1-31 Text Annotation Attributes name NULL text color NULL color color YELLOW font integer 1 justification toggle 0 x position double 0.0 y position double 0.0 width double 0.0 height double 0.0 subnet object ID 1 End of Table object ID of surrounding subnet object. MFA-1-44 Modeler/Release 10.0

45 Self-Description Table 1-32 Self-Description Objects Object Type required self-description assigned self-description core self-description node self-description Symbolic Constant OBJ_SELFDESC_REQ OBJ_SELFDESC_ASSGN OBJ_SELFDESC_CORE OBJ_SELFDESC_PORTGROUP End of Table 1-32 Table 1-33 Required Self-Description Object Attributes characteristic "" comparator integer 1 OPC_SELFDESC_CMP_EQUALS value "" End of Table symbolic constant values for this attribute appear in Table Self-Description Comparator Symbolic Constants on page MFA Table 1-34 Assigned Self-Description Object Attributes attribute "" type integer 1 OPC_SELFDESC_ASSGN_CONST value "" requirements array of object IDs 2 assignments array of object IDs 3 "" OPC_SELFDESC_ASSGN_CONST priority integer 0 End of Table symbolic constant values for this attribute appear in Table Self-Description Assignment Type Symbolic Constants on page MFA object IDs of required self-descriptions. 3. object IDs of assigned self-descriptions. Modeler/Release 10.0 MFA-1-45

46 Table 1-35 Portgroup Self-Description Object Attributes portgroup core object IDs 1 lower range integer 0 upper range integer 0 receiver "" transmitter "" padding integer 0 End of Table object ID of core self-description object. MFA-1-46 Modeler/Release 10.0

47 Node Model Table 1-36 Node Objects Object Type position interface description attribute assignment processor queue external system module point-to-point transmitter point-to-point receiver bus transmitter bus receiver subqueue pt.-to-pt. trans. channel pt.-to-pt. rec. channel bus transmitter channel bus receiver channel stream statistics wire statistic interface description logical association Symbolic Constant OBJ_ND_POS OBJ_ND_INTF_DESC OBJ_ND_ATTR_ASSGN OBJ_ND_PROCESSOR OBJ_ND_QUEUE OBJ_ND_ESYS OBJ_ND_PT_TX OBJ_ND_PT_RX OBJ_ND_BU_TX OBJ_ND_BU_RX OBJ_ND_SUBQ OBJ_ND_PT_TXCH OBJ_ND_PT_RXCH OBJ_ND_BU_TXCH OBJ_ND_BU_RXCH OBJ_ND_STRM OBJ_ND_STATWIRE OBJ_ND_STAT_INTF OBJ_ND_ASSOC End of Table 1-36 Modeler/Release 10.0 MFA-1-47

48 Table 1-37 Node Model Attributes stat intf descs array of object IDs 1 interface descriptions array of object IDs 2 attribute assignments array of object IDs 3 model comments textlist 4 keywords textlist 5 fixed icon 6 (empty) (empty) (empty) mobile icon f (empty) satellite icon f (empty) doc file (empty) tooltip (empty) End of Table object IDs of interface description objects for statistics. 2. object IDs of interface description objects for the model. 3. object IDs of attribute assignment objects. 4. textlist containing description of model. 5. textlist containing keywords (one per line) used in palette. 6. name of icon to use for this type of node. Table 1-38 Position Object Attributes x y set-required double set-required double End of Table 1-38 Table 1-39 Interface Description Object Attributes (Part 1 of 2) Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 MFA-1-48 Modeler/Release 10.0

49 Table 1-39 Interface Description Object Attributes (Part 2 of 2) Name Type 1 Default properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Modeler/Release 10.0 MFA-1-49

50 Table 1-40 Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table 1-41 Processor Object Attributes name set-required process model 1 intrpt interval toggle double 2 "sink" (disabled) begsim intrpt toggle EMAC_DISABLED endsim intrpt toggle EMAC_DISABLED failure intrpts 3 "disabled" recovery intrpts c "disabled" icon name 4 "processor" position object ID 5 priority integer 0 super priority toggle EMAC_DISABLED doc file "nd_module" End of Table name of process model, without suffix. 2. in units of seconds. 3. valid values: "disabled", "local only", and "model wide". 4. name of icon in an icon database. 5. object ID of position object. MFA-1-50 Modeler/Release 10.0

51 Table 1-42 Queue Object Attributes name set-required subqueue object ID 1 process model 2 intrpt interval toggle double 3 "pc_fifo" (disabled) begsim intrpt toggle EMAC_DISABLED endsim intrpt toggle EMAC_DISABLED failure intrpts 4 "disabled" recovery intrpts d "disabled" icon name 5 "queue" position object ID 6 priority integer 0 super priority toggle EMAC_DISABLED doc file "nd_module" End of Table object ID of subqueue compound value object. The subqueue compound value object is an EMA base object, containing the list and count attributes. Sub-objects named by list are subqueue compound objects described below. 2. name of process model, without suffix. 3. in units of seconds. 4. valid values: "disabled", "local only", and "model wide". 5. name of icon in an icon database. 6. object ID of position object. Table 1-43 Subqueue Compound Object Attributes pk capacity double EMAC_DBL_INFINITY (pks) bit capacity double EMAC_DBL_INFINITY (bits) End of Table 1-43 Modeler/Release 10.0 MFA-1-51

52 Table 1-44 External System Module Attributes name set-required process model 1 esd model 2 icon name 3 sink NONE esys_module begsim intrpt toggle EMAC_DISABLED doc file nd_module endsim intrpt toggle EMAC_DISABLED failure intrpts 4 intrpt interval toggle double 5 disabled (disabled) priority integer 0 recovery intrpts d disabled subqueue object ID 6 super priority toggle EMAC_DISABLED position object ID 7 End of Table name of process model, without suffix. 2. name of external system description file, without suffix. 3. name of icon in an icon database. 4. valid values: disabled, local only, and model wide. 5. in units of seconds. 6. object ID of subqueue compound value object. The subqueue compound value object is an EMA base object, containing the list and count attributes. 7. object ID of position object. MFA-1-52 Modeler/Release 10.0

53 In the following tables, the value of all channel attributes specified for receiver and transmitter objects is the object ID of a compound value object. The compound value object is an EMA base object, containing the list and count attributes. Sub-objects named by list are channel objects described later in this section. Table 1-45 Point-to-Point Receiver Object Attributes name set-required channel object ID 1 ecc threshold double 0.0 (err/bit) icon name 2 "pt_rx" position object ID 3 doc file "nd_ptp_receiver" End of Table object ID of point-to-point receiver channel compound value object. 2. name of icon in an icon database. 3. object ID of position object. Table 1-46 Bus Receiver Object Attributes name set-required channel object ID 1 ecc threshold double 0.0 (err/bit) icon name 2 "bu_rx" position object ID 3 doc file "nd_bus_receiver" End of Table object ID of bus receiver channel compound value object. 2. name of icon in an icon database. 3. object ID of position object. Modeler/Release 10.0 MFA-1-53

54 Table 1-47 Point-to-Point Transmitter Object Attributes name set-required channel object ID 1 icon name 2 "pt_tx" position object ID 3 doc file "nd_ptp_transmitter" End of Table object ID of point-to-point transmitter channel compound value object. 2. name of icon in an icon database. 3. object ID of position object. Table 1-48 Bus Transmitter Object Attributes name set-required channel object ID 1 icon name 2 "bu_tx" position object ID 3 doc file "nd_bus_transmitter" End of Table object ID of bus transmitter channel compound value object. 2. name of icon in an icon database. 3. object ID of position object. Table 1-49 Point-to-Point Receiver Channel Object Attributes data rate double (bps) packet formats 1 OPC_NT_LINK_ALLPKS End of Table names of packet formats, separated by commas. MFA-1-54 Modeler/Release 10.0

55 Table 1-50 Point-to-Point Transmitter Channel Object Attributes data rate double (bps) packet formats 1 OPC_NT_LINK_ALLPKS End of Table names of packet formats, separated by commas. Table 1-51 Bus Receiver Channel Object Attributes data rate double (bps) packet formats 1 OPC_NT_LINK_ALLPKS End of Table names of packet formats, separated by commas. Table 1-52 Bus Transmitter Channel Object Attributes data rate double (bps) packet formats 1 OPC_NT_LINK_ALLPKS End of Table names of packet formats, separated by commas. Table 1-53 Stream Object Attributes (Part 1 of 2) Name Alias Type Default name src stream src strm set-required integer 0 dest stream dest strm set-required integer 0 color gfx color integer 1 OPC_GFX_COLOR_GREEN intrpt method integer 2 OPC_INTRPT_METHOD_SCHED delay double 0.0 (sec) src module set-required object ID 3 Modeler/Release 10.0 MFA-1-55

56 Table 1-53 Stream Object Attributes (Part 2 of 2) Name Alias Type Default dest module set-required object ID c path array of object IDs 4 doc file "nd_packet_stream" End of Table symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Interrupt Method Symbolic Constants on page MFA object ID of connected module object. 4. object IDs of position objects that define stream path. Table 1-54 Statistic Wire Object Attributes Name Alias Type Default name delay double 0.0 (sec) color gfx color integer 1 OPC_GFX_COLOR_RGB331 src stat set-required 2 dest stat set-required integer 3 0 intrpt method integer 4 OPC_INTRPT_METHOD_SCHED src module set-required object ID 5 dest module set-required object ID 6 trigger integer 7 OPC_TRIG_RISING_EDGE path array of object IDs 8 low thresh double 0.0 high thresh double 0.0 OPC_TRIG_FALLING_EDGE doc file "nd_statistic_wire" End of Table symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA name of source module statistic (submodule statistics are prefixed by the submodule index, in brackets; e.g., [2].pksize ); see Chapter 2 Node Reference on page MR-2-1 in the Modeling Reference manual for a list of supported module statistics. 3. numeric index of destination processor or queue input statistic. MFA-1-56 Modeler/Release 10.0

57 4. symbolic constant values for this attribute appear in Table Interrupt Method Symbolic Constants on page MFA object ID of connected module object. 6. object ID of connected processor or queue object. 7. symbolic constant values for this attribute appear in Table Statistic Wire Trigger Symbolic Constants on page MFA object IDs of position objects that define statistic wire path. Table 1-55 Statistic Interface Description Object Attributes original name promoted name description toggle textlist 1 (empty) group name capture mode display mode original group name End of Table textlist containing description of statistic. Table 1-56 Logical Tx/Rx Association Object Attributes Name Alias Type Default name color gfx color integer 1 OPC_GFX_COLOR_ORANGE src module set-required object ID 2 dest module set-required object ID 3 path array of object IDs 4 doc file "nd_association" End of Table symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA object ID of connected transmitter or receiver module object. 3. object ID of connected transmitter or receiver module object. 4. object IDs of position objects that define association path. Modeler/Release 10.0 MFA-1-57

58 Process Model Table 1-57 Process Objects Object Type position interface description attribute assignment state transition statistic description Symbolic Constant OBJ_PR_POS OBJ_PR_INTF_DESC OBJ_PR_ATTR_ASSGN OBJ_PR_STATE OBJ_PR_TRANS OBJ_PR_STAT_DESC End of Table 1-57 Table 1-58 Position Object Attributes x y set-required double set-required double End of Table 1-58 Table 1-59 Process Model Attributes (Part 1 of 2) state vars textlist 1 (empty) temp vars textlist a (empty) header block textlist a (empty) function block textlist a (empty) diag block textlist a (empty) termination block textlist a (empty) child processes textlist 2 (empty) ext fileset textlist 3 (empty) simulation attributes array of object IDs 4 (empty) global stat descs array of object IDs 5 (empty) local stat descs array of object IDs e (empty) MFA-1-58 Modeler/Release 10.0

59 Table 1-59 Process Model Attributes (Part 2 of 2) model comments textlist 6 (empty) interface descriptions array of object IDs 7 attribute assignments array of object IDs 8 packet formats textlist 9 End of Table textlists containing Proto-C statements (see Chapter 5 Process Domain on page MC-5-1 in the Modeling Concepts manual for syntax guidelines). 2. textlist containing names of process models, without suffixes. 3. textlist containing names of external object files, without suffixes. 4. object IDs of attribute definition objects. 5. object IDs of statistic description objects. 6. textlist containing description of model. 7. object IDs of interface description objects for the model. 8. object IDs of attribute assignment objects. 9. textlist containing names of packet formats, without suffixes. Modeler/Release 10.0 MFA-1-59

60 Table 1-60 Interface Description Object Attributes Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table 1-61 Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table 1-62 State Object Attributes Name Alias Type Default name enter execs textlist 1 (empty) exit execs textlist a (empty) status forced toggle 2 EMAC_DISABLED position object ID 3 initial toggle 4 EMAC_DISABLED End of Table 1-62 MFA-1-60 Modeler/Release 10.0

61 1. textlists containing Proto-C statements (see Chapter 5 Process Domain on page MC-5-1 in the Modeling Concepts manual for syntax guidelines). 2. EMAC_DISABLED indicates state is unforced; EMAC_ENABLED indicates state is forced. 3. object ID of position object. 4. EMAC_ENABLED indicates state is initial. Table 1-63 Transition Object Attributes Name Alias Type Default name condition 1 executive 2 dest state set-required object ID 3 src state set-required object ID c drawing style spline toggle 4 EMAC_ENABLED color gfx color integer 5 OPC_GFX_COLOR_WHITE path array of object IDs 6 label pos object ID 7 End of Table containing Proto-C Boolean expression (see Chapter 5 Process Domain on page MC-5-1 in the Modeling Concepts manual for syntax guidelines). 2. containing Proto-C statement. 3. object ID of process state object. 4. EMAC_DISABLED indicates line drawing style; EMAC_ENABLED indicates spline drawing style. 5. symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA object IDs of position objects that define transition path. 7. object ID of position object for transition label. Table 1-64 Statistic Description Object Attributes (Part 1 of 2) name count toggle integer EMA_DISABLED description textlist 1 (empty) group name Modeler/Release 10.0 MFA-1-61

62 Table 1-64 Statistic Description Object Attributes (Part 2 of 2) capture mode display mode low bound toggle double EMAC_DISABLED high bound toggle double EMAC_DISABLED End of Table textlist containing description of attribute. MFA-1-62 Modeler/Release 10.0

63 External System Definition Table 1-65 External System Objects Name Interface External system definition Symbolic constant OBJ_ESD_INTERFACE OBJ_ESD_BASE End of Table 1-65 Table 1-66 Interface Object Attributes name set required comment type 1 direction 2 set required integer integer integer OPC_ESYS_DIR_IN dimension 3 integer 0 offset integer (EMA only) 0 End of Table The type attribute specifies the type of data that can be placed on the interface. Symbolic constant values for this attribute appear in Table External System Interface Type Symbolic Constants on page MFA The direction attribute indicates flow of data relative to the external system (therefore, in is OPNET-to-cosimulation). Symbolic constant values for this attribute appear in Table External System interface Direction Symbolic Constants on page MFA The dimension attribute of interface objects refers to vector interfaces. The default value of zero means that the interface is not a vector interface. See Chapter 8 External System Domain on page MC-8-1 in the Modeling Concepts manual for more information about vector interfaces. Table 1-67 External System Definition Object Attributes name set required simulator NONE source description End of Table 1-67 Modeler/Release 10.0 MFA-1-63

64 Table 1-68 Model Attributes of External System Definition model comments textlist (EMA only) End of Table 1-68 MFA-1-64 Modeler/Release 10.0

65 Link Model Table 1-69 Link Objects Object Type interface description attribute assignment self description ETS handler function statistic description Symbolic Constant OBJ_LNK_INTF_DESC OBJ_LNK_ATTR_ASSGN OBJ_SELFDESC_CORE OBJ_LNK_ETS_HANDLER OBJ_LNK_STAT_DESC End of Table 1-69 l Table 1-70 Link Model Attributes model comments textlist 1 (empty) keywords textlist 2 simplex link icon duplex link icon bus link icon bus tap icon selfdescription array of object IDs 3 tooltip (empty ) doc file (empty ) ets handlers array of object IDs 4 local stat descs array of object IDs 5 interface descriptions array of object IDs 6 attribute assignments array of object IDs 7 selfdescription object ID 8 End of Table textlist containing description of model. 2. textlist containing keywords (one per line) used in palette. 3. object IDs of type Vc_Selfdesc_Type Modeler/Release 10.0 MFA-1-65

66 4. object IDs of type Vc_ETS_Handler_Type 5. object IDs of type Vc_Stat_Desc_Types 6. object IDs of interface description objects for the model. 7. object IDs of attribute assignment objects. 8. object ID of OBJ_SELFDESC_CORE. Table 1-71 Interface Description Object Attributes Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table 1-72 Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. MFA-1-66 Modeler/Release 10.0

67 Path Model Table 1-73 Path Objects Object Type interface description attribute assignment self description ETS handler function statistic description Symbolic Constant OBJ_PATH_INTF_DESC OBJ_PATH_ATTR_ASSGN OBJ_SELFDESC_CORE OBJ_PATH_ETS_HANDLER OBJ_PATH_STAT_DESC End of Table 1-73 l Table 1-74 Path Model Attributes model comments textlist 1 (empty) keywords textlist 2 (empty) tooltip (empty ) doc file (empty ) icon (empty ) connectivity (empty ) ignore subnets Boolean integer 0 allow cycles Boolean integer 0 two endpoints only Boolean integer 0 packet formats all formats 3 selfdescription array of object IDs 4 ets handlers array of object IDs 5 local stat descs array of object IDs 6 interface descriptions array of object IDs 7 attribute assignments array of object IDs 8 selfdescription object ID 9 End of Table 1-74 Modeler/Release 10.0 MFA-1-67

68 1. textlist containing description of model. 2. textlist containing keywords (one per line) used in palette. 3. specifying all valid packet formats 4. object IDs of type Vc_Selfdesc_Type 5. object IDs of type Vc_ETS_Handler_Type 6. object IDs of type Vc_Stat_Desc_Types 7. object IDs of interface description objects for the model. 8. object IDs of attribute assignment objects. 9. object ID of OBJ_SELFDESC_CORE. Table 1-75 Interface Description Object Attributes Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table 1-76 Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. MFA-1-68 Modeler/Release 10.0

69 Probability Density Function Table 1-77 PDF Objects Object Type impulse Symbolic Constant OBJ_PDF_IMPULSE End of Table 1-77 Table 1-78 PDF Model Attributes outcome min double outcome spacing double 0.5 prob density double vector End of Table 1-78 Table 1-79 Impulse Object Attributes outcome mass double double End of Table 1-79 Modeler/Release 10.0 MFA-1-69

70 ICI Format Table 1-80 ICI Format Objects Object Type attribute descriptor Symbolic Constant OBJ_ICF_ATTR_DESC End of Table 1-80 Table 1-81 ICI Format Model Attributes -- No attributes are defined for this model type -- End of Table 1-81 Table 1-82 ICI Attribute Descriptor Object Attributes type integer 1 OPC_ICA_TYPE_INTEGER default value name End of Table symbolic constant values for this attribute appear in Table ICI Attribute Type Symbolic Constants on page MFA MFA-1-70 Modeler/Release 10.0

71 Packet Format Table 1-83 Packet Model Attributes comments textlist bulk fill pattern "0x0" conversion method "none" supports conversion toggle EMAC_ENABLED bulk fill pattern "0x0" End of Table 1-83 Table 1-84 Packet Field Object Attributes name comments set required textlist type integer 1 encoding 2 size integer 3 OPC_PKF_TYPE_INTEGER OPC_PKF_ENCODING_SIGNED_BIGE 32 default value set at creation toggle INIT_ENABLED color integer OPC_GFX_COLOR_GREY conversion method "NONE" conversion order position integer Object ID End of Table symbolic constant values for this attribute appear in Table Packet Field Type Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Packet Encoding Attribute Symbolic Constants on page MFA in bits. Modeler/Release 10.0 MFA-1-71

72 Probe List Table 1-85 Probe List Objects Object Type position node statistic probe automatic animation probe custom animation probe simulation attribute probe global statistic probe statistic animation probe link probe Symbolic Constant OBJ_PB_POS OBJ_PB_SPROBE OBJ_PB_AAPROBE OBJ_PB_CAPROBE OBJ_PB_SAPROBE OBJ_PB_GSPROBE OBJ_PB_STANPROBE OBJ_PB_LKPROBE End of Table 1-85 Table 1-86 Probe List Model Attributes network name 1 End of Table name of network model, without suffix. Table 1-87 Position Object Attributes x y set-required double set-required double End of Table 1-87 Table 1-88 Statistic Probe Object Attributes (Part 1 of 2) Name Alias Type Default name subnet 1 node 2 module 3 MFA-1-72 Modeler/Release 10.0

73 Table 1-88 Statistic Probe Object Attributes (Part 2 of 2) Name Alias Type Default submodule 4 statistic 5 ordinate label vector data toggle EMAC_ENABLED vector start start time double 0.0 (sec) vector stop stop time double EMAC_DBL_INFINITY (sec) capture mode 6 "normal" scalar data toggle EMAC_DISABLED scalar type end log 7 scalar start double 0.0 scalar stop double EMAC_DBL_INFINITY (sec) pos object ID 8 doc file "pb_node_stat_probe" drawing style group threshold comparison "disabled" threshold value double 0.0 threshold percent double 90.0 tag OVC_VECTOR_TAG_USER low bound toggle EMAC_DISABLED high bound toggle EMAC_DISABLED End of Table name of subnet in associated network model. 2. name of node in associated network model. 3. name of module in node model referenced by associated network model. 4. formal name of submodule (e.g., "subqueue [0]"). 5. name of statistic supported by referenced module or submodule; see Chapter 2 Node Reference on page MR-2-1 of the Modeling Reference manual for a list of supported module statistics. Modeler/Release 10.0 MFA-1-73

74 6. valid values: "normal", "sample/<n>", "bucket/<n>/<mode>", "glitch removal"; where <n> is either a number (double) or a number followed by "sec"; <mode> is either "max value", "min value", "sum", "count", "sample mean", or "time average. 7. valid values: "last value", "sample mean", "time average", "variance", "min value", "max value". 8. object ID of position object. MFA-1-74 Modeler/Release 10.0

75 Table 1-89 Automatic Animation Probe Object Attributes name subnet 1 node 2 module 3 representation 4 anim start double 0.0 (sec) anim stop double EMAC_DBL_INFINITY (sec) window name window x integer 10 (pixels) window y integer 10 (pixels) window width integer 500 (pixels) window height integer 300 (pixels) pos object ID 5 doc file "pb_auto_anim_probe" End of Table name of subnet in associated network model. 2. name of node in associated network model. 3. name of module in node model referenced by associated network model. 4. name of automatic animation representation supported by referenced object. 5. object ID of position object. Table 1-90 Custom Animation Probe Object Attributes (Part 1 of 2) name subnet 1 node 2 module 3 label Modeler/Release 10.0 MFA-1-75

76 Table 1-90 Custom Animation Probe Object Attributes (Part 2 of 2) anim start double 0.0 (sec) anim stop double EMAC_DBL_INFINITY (sec) window name window x integer 10 (pixels) window y integer 10 (pixels) window width integer 500 (pixels) window height integer 300 (pixels) pos object ID 4 doc file "pb_custom_anim_probe" End of Table name of subnet in associated network model. 2. name of node in associated network model. 3. name of module in node model referenced by associated network model. 4. object ID of position object. MFA-1-76 Modeler/Release 10.0

77 Table 1-91 Attribute Probe Object Attributes name object 1 attribute 2 ordinate label pos object ID 3 doc file "pb_attribute_probe" End of Table full hierarchical name of probed object (empty for simulation attributes). 2. name of probed object s attribute (simulation attribute name if a simulation attribute is referenced). 3. object ID of position object. Table 1-92 Global Statistic Probe Object Attributes (Part 1 of 2) name global statistic 1 ordinate label vector data toggle EMAC_ENABLED vector start double 0.0 (sec) vector stop double EMAC_DBL_INFINITY (sec) capture mode 2 "normal" scalar data toggle EMAC_DISABLED scalar type 3 scalar start double 0.0 scalar stop double EMAC_DBL_INFINITY (sec) pos object ID 4 doc file "pb_global_stat_probe" group "disabled" threshold comparison double 0.0 Modeler/Release 10.0 MFA-1-77

78 Table 1-92 Global Statistic Probe Object Attributes (Part 2 of 2) threshold value double 90.0 threshold percent OVC_VECTOR_TAG_USER tag toggle EMAC_DISABLED low bound toggle EMAC_DISABLED End of Table name of global statistic. 2. valid values: "normal", "sample/<n>", "bucket/<n>/<mode>", "glitch removal"; where <n> is either a number (double) or a number followed by "sec"; <mode> is either "max value", "min value", "sum", "count", "sample mean", or "time average. 3. valid values: "last value", "sample mean", "time average", "variance", "min value", "max value". 4. object ID of position object. MFA-1-78 Modeler/Release 10.0

79 Table 1-93 Statistic Animation Probe Object Attributes name statistic 1 window name 2 window x integer 10 window y integer 10 window width integer 500 window height integer 400 panel name 3 panel x integer 10 panel y integer 10 panel width integer 442 panel height integer 440 zone number integer 1 zone height integer 200 zone color integer OPC_GFX_COLOR_STEEL background color integer OPC_GFX_COLOR_SLATE scrolling toggle EMAC_DISABLED initial width double 0.0 trace color integer OPC_GFX_COLOR_WHITE trace style "linear" pos object ID 4 doc file "pb_stat_anim_probe" End of Table name of statistic probe. 2. name of window in which to display this statistic; this window can display only Statistic Animation Probes. 3. name of panel within named window in which to display this statistic. 4. object ID of position object. Modeler/Release 10.0 MFA-1-79

80 Table 1-94 Link Probe Object Attributes name subnet 1 link 2 channel 3 statistic 4 ordinate label vector data toggle EMAC_ENABLED vector start double 0.0 (sec) vector stop double EMAC_DBL_INFINITY (sec) capture mode 5 "normal" scalar data toggle EMAC_DISABLED scalar type 6 scalar start double 0.0 scalar stop double EMAC_DBL_INFINITY (sec) pos object ID 7 doc file "pb_link_stat_probe" drawing style group threshold comparison double 0.0 threshold value double 90.0 threshold percent OVC_VECTOR_TAG_USER tag toggle EMAC_DISABLED low bound toggle EMAC_DISABLED End of Table name of subnet in associated network model. 2. name of link. 3. name of channel. MFA-1-80 Modeler/Release 10.0

81 4. name of statistic supported by referenced module or submodule; see Chapter 2 Node Reference on page MR-2-1 of the Modeling Reference manual for a list of supported module statistics. 5. valid values: "normal", "sample/<n>", "bucket/<n>/<mode>", "glitch removal"; where <n> is either a number (double) or a number followed by "sec"; <mode> is either "max value", "min value", "sum", "count", "sample mean", or "time average. 6. valid values: "last value", "sample mean", "time average", "variance", "min value", "max value". 7. object ID of position object. Modeler/Release 10.0 MFA-1-81

82 Simulation Sequence Table 1-95 Simulation Sequence Objects Object Type position simulation argument simulation run Symbolic Constant OBJ_SEQ_POS OBJ_SEQ_ARG OBJ_SEQ_RUN End of Table 1-95 Table 1-96 Simulation Sequence Model Attributes -- No attributes are defined for this model type -- End of Table 1-96 Table 1-97 Position Object Attributes x y set-required double set-required double End of Table 1-97 Table 1-98 Simulation Argument Object Attributes value 1 "TRUE" name 2 End of Table String representing the value or values that the attribute names by "name" is to take on. If multiple values are to be listed, they are separated by the character (e.g. the " " represents three values that an attribute will take on). 2. The name of the attribute for which a value or values are provided. MFA-1-82 Modeler/Release 10.0

83 Table 1-99 Simulation Run Object Attributes (Part 1 of 2) Name Alias Type Default name aim program 1 "op_runsim" network 2 probe file 3 vector file output file 4 scalar file log file 5 seed integer duration double update interval toggle double g noprompt toggle EMAC_DISABLED environment files textlist 8 (empty) anim attempts integer 5 anim hist 9 anim host "localhost" anim post integer 0 anim timeout double 3.0 anim view toggle EMAC_DISABLED anim hist enabled toggle EMAC_DISABLED multi vector files toggle EMAC_DISABLED argument list array of object IDs 10 pos object ID 11 collect count integer 100 tim file enable logging toggle EMAC_DISABLED doc file SLA probe files textlist l (empty) Modeler/Release 10.0 MFA-1-83

84 Table 1-99 Simulation Run Object Attributes (Part 2 of 2) Name Alias Type Default Report probe files textlist m (empty) Start date Start time Date recording "not set" Generate web report toggle EMAC_DISABLED End of Table name of simulation program. 2. name of network model file, without suffix. 3. name of probe list file, without suffix. 4. name of output vector file, without suffix. 5. name of output scalar file, without suffix. 6. seed number given to random number generator. 7. in units of seconds. 8. textlist containing list of environmental files. 9. name of animation history file. 10. object IDs of child simulation argument objects. 11. object ID of position object. l. textlist containing list of SLA probe files m. textlist containing list of web report probe files MFA-1-84 Modeler/Release 10.0

85 Output Vector Table Output Vector Objects Object Type vector element Symbolic Constant OBJ_OV_VECTOR OBJ_OV_ELEMENT End of Table Table Output Vector Model Attributes root element object ID 1 End of Table This is the object ID for the root node object. The value EMAC_NULL_OBJ_ID means the model has a flat structure. Table Output Vector Object Attributes (Part 1 of 2) abscissa name ordinate name type integer 1 OPC_OV_TYPE_VECTOR_DOUBLE enum dictionary time delta double 0 time start double 0 drawing style integer 2 OPC_OV_DRAW_STYLE_LINEAR abscissa vec ordinate vec double vector double vector time units integer 3 OPC_OV_TIME_UNITS_SECONDS threshold mode integer 4 OPC_OV_THRESHOLD_MODE_NONE threshold value double 0.0 threshold percent double 0.0 low bound toggle EMAC_DISABLED high bound toggle EMAC_DISABLED Modeler/Release 10.0 MFA-1-85

86 Table Output Vector Object Attributes (Part 2 of 2) minimum vec maximum vec std dev vec threshold total vec threshold violations vec start date start time double vector double vector double vector double vector double vector trend time units integer 3 OPC_OV_TIME_UNITS_SECONDS trend time delta toggle EMAC_DISABLED End of Table symbolic constant values for this attribute appear in Table Output Vector Subelement Type Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Output Vector Drawing Style Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Output Vector Time Unit Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Output Vector Threshold Mode Symbolic Constants on page MFA Table Output Vector Element Object Attributes type integer 1 OPC_OV_TYPE_OBJECT name subelement array of object IDs 2 End of Table symbolic constant values for this attribute appear in Table Output Vector Subelement Type Symbolic Constants on page MFA object IDs of either vector or node objects. MFA-1-86 Modeler/Release 10.0

87 Output Scalar Table Output Scalar Objects Object Type simulation run statistic Symbolic Constant OBJ_OS_RUN OBJ_OS_STAT End of Table Table Output Scalar Model Attributes -- No attributes are defined for this model type -- End of Table Table Output Scalar Run Object Attributes model name set-required 1 seed set-required integer 0 stat array array of object IDs 2 End of Table name of simulation executable, without suffix. 2. object IDs of output scalar run statistic objects. Table Output Scalar Run Statistic Object Attributes name set-required value set-required double 0.0 End of Table Modeler/Release 10.0 MFA-1-87

88 Cartographic Data Set Table Cartographic Data Set Objects Object Type line object (city, label, etc.) Symbolic Constant OBJ_CDS_LINE OBJ_CDS_OBJECT End of Table Table Cartographic Data Set Attributes grid division double 15.0 grid color integer 1 grid style integer 2 OPC_GFX_COLOR_RGB222 OPC_GRID_STYLE_NONE End of Table symbolic constant values for this attribute appear in Table Graphics Color Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Grid Style Symbolic Constants on page MFA Table Line Object Attributes Name Alias Type Default status toggle EMAC_ENABLED condition toggle EMAC_ENABLED color integer 1 OPC_GFX_COLOR_RGB221 rank integer 0 type integer 2 OPC_CDS_LINE_TYPE_COAST threshold double 0.0 (pixels/deg) latitude double vector 3 longitude double vector c End of Table symbolic constant values for these attributes appear in Table Graphics Color Symbolic Constants on page MFA symbolic constant values for this attribute appear in Table Cartographic Line Type Symbolic Constants on page MFA vector values in units of degrees. MFA-1-88 Modeler/Release 10.0

89 Table Cartographic Object Attributes Name Alias Type Default longitude x position double 0.0 latitude y position double 0.0 name icon name icon 1 "city_marker" threshold double 0.0 (pixels/deg) draw icon toggle EMAC_ENABLED text size integer 2 text color integer 3 OPC_TEXT_SIZE_SMALL OPC_GFX_COLOR_RGB333 End of Table name of icon in opnet, sys, or user icon databases. 2. symbolic constants for this attribute appear in Table Text Size Symbolic Constants on page MFA symbolic constants for this attribute appear in Table Graphics Color Symbolic Constants on page MFA Public Attribute Description Model Table Public Attribute Description Model Objects Object Type properties Symbolic Constant OBJ_ATTR_PROPS End of Table Table Public Attribute Description Model Attributes properties set-required object ID 1 End of Table object ID of properties object. Modeler/Release 10.0 MFA-1-89

90 Derived Node Model Table Derived Node Model Objects Object Type interface description attribute assignment Symbolic Constant OBJ_NDDER_INTF_DESC OBJ_NDDER_ATTR_ASSGN End of Table Table Derived Node Model Attributes fixed icon 1 parent model model comments textlist 2 keywords textlist 3 (empty) (empty) interface descriptions array of object IDs 4 attribute assignments array of object IDs 5 selfdescription object ID 6 inherit selfdescription toggle EMAC_ENABLED tooltip doc file End of Table name of icon to use for this type of node. 2. textlist containing description of model. 3. textlist containing keywords (one per line) used in palette. 4. object IDs of interface description objects for the model. 5. object IDs of attribute assignment objects. 6. object ID of OBJ_SELFDESC_PORTGROUP. MFA-1-90 Modeler/Release 10.0

91 Table Interface Description Object Attributes Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Modeler/Release 10.0 MFA-1-91

92 Derived Link Model Table Derived Link Model Objects Object Type interface description attribute assignment Symbolic Constant OBJ_LNKDER_INTF_DESC OBJ_LNKDER_ATTR_ASSGN End of Table Table Derived Link Model Attributes duplex link icon 1 simplex link icon bus link icon bus tap icon parent model a a a model comments textlist 2 keywords textlist 3 (empty) (empty) interface descriptions array of object IDs 4 attribute assignments array of object IDs 5 selfdescription object ID 6 inherit selfdescription toggle EMAC_ENABLED tooltip doc file End of Table name of icon to use for this type of link. 2. textlist containing description of model. 3. textlist containing keywords (one per line) used in palette. 4. object IDs of interface description objects for the model. 5. object IDs of attribute assignment objects. 6. object ID of OBJ_SELFDESC_CORE. MFA-1-92 Modeler/Release 10.0

93 Table Interface Description Object Attributes Name Type 1 Default promotion name merged names set-required set-required textlist flags integer 0 properties object ID suppressed symbols textlist (empty) type integer -1 End of Table See notes for Table 1-20 Interface Description Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Table Attribute Assignment Object Attributes Name Type 1 Default name operation value integer poly type integer -1 End of Table See notes for Table 1-21 Attribute Assignment Object Attributes on page MFA-1-34 for more complete details on specific attribute meanings. Symbol Map Object Table Symbol Map Object Object Type symbol map Symbolic Constant OBJ_ATTR_SYMMAP End of Table Modeler/Release 10.0 MFA-1-93

94 OPNET Attribute Symbolic Constants Some of the OPNET model and object attributes accessible through EMA are integers that can take on several values, each of which has a special symbolic meaning (i.e., codes or flags). For convenience, the possible values for these attributes are represented by the symbolic constants listed in this section. The substituted values of these constants are subject to change in new releases, so it is not advisable to use the actual numeric constants instead of the symbolic constants. The grid unit symbolic constants listed below identify the type of grid that is used inside a subnet to measure node and link positions. These constants can be assigned to the grid unit attribute of the subnet object within the network model. The grid unit value assigned to this subnet attribute determines the unit interpretation of all grid and position related attributes of network objects (in the network attribute tables in Models, Objects, and Attributes on page MFA-1-26, grid-based attribute units are indicated by the designation subnet grid unit ). Table Grid Unit Symbolic Constants OPC_GRID_UNIT_NONE OPC_GRID_UNIT_DEG OPC_GRID_UNIT_MILE OPC_GRID_UNIT_KILOMETER OPC_GRID_UNIT_METER OPC_GRID_UNIT_FOOT End of Table The grid style symbolic constants listed below are used to specify the appearance of the grid within a subnet. These constants can be assigned to the grid style attribute of subnet objects within network models. Table Grid Style Symbolic Constants OPC_GRID_STYLE_NONE OPC_GRID_STYLE_SOLID OPC_GRID_STYLE_DASHED End of Table MFA-1-94 Modeler/Release 10.0

95 The graphics color symbolic constants listed below are used to indicate color preferences for objects or object sub-components. These constants are usually assigned to the color attribute of objects. The following objects support this attribute: network model (satellite node, mobile node, simplex point-to-point link, duplex point-to-point link, bus link, bus tap) node model (stream, statistic wire) external system definition (esys interface) process model (transition) In addition, network model subnets support the color attributes outline color and grid color. Table Graphics Color Symbolic Constants (Part 1 of 2) OPC_GFX_COLOR_BEIGE OPC_GFX_COLOR_BLACK OPC_GFX_COLOR_BLUE OPC_GFX_COLOR_BRICK OPC_GFX_COLOR_BROWN OPC_GFX_COLOR_CORN OPC_GFX_COLOR_CYAN 1 OPC_GFX_COLOR_FUCHSIA OPC_GFX_COLOR_GREEN OPC_GFX_COLOR_GREY OPC_GFX_COLOR_MAGENTA OPC_GFX_COLOR_MAROON OPC_GFX_COLOR_OLIVE OPC_GFX_COLOR_ORANGE OPC_GFX_COLOR_ORCHID OPC_GFX_COLOR_PEACH OPC_GFX_COLOR_PINK OPC_GFX_COLOR_PLUM OPC_GFX_COLOR_PURPLE OPC_GFX_COLOR_RED OPC_GFX_COLOR_SIENNA OPC_GFX_COLOR_SLATE OPC_GFX_COLOR_STEEL OPC_GFX_COLOR_TAN Modeler/Release 10.0 MFA-1-95

96 Table Graphics Color Symbolic Constants (Part 2 of 2) OPC_GFX_COLOR_TURQ 1 OPC_GFX_COLOR_VIOLET OPC_GFX_COLOR_WHITE OPC_GFX_COLOR_YELLOW End of Table CYAN and TURQ represent the same color value. In addition to the named graphics color symbolic constants listed above, there is a set of defined symbolic constants for colors specified in terms of red, green, and blue (RGB) components. The graphic user interface (GUI) supports 64 different colors based on the 64 RGB permutations of 4 brightness levels per color (64 = 4 x 4 x 4). The format of the RGB-based symbolic constants is: OPC_GFX_COLOR_RGB<r><g><b> where <r>, <g>, and <b> can take the values 0, 1, 2, and 3. The limiting cases in this format are black (OPC_GFX_COLOR_RGB000), and white (OPC_GFX_COLOR_RGB333). The interrupt method symbolic constants listed below are used to specify the type of interrupt that will be caused by packet arrivals or statistic wire triggers. These constants can be assigned to the intrpt method attribute of the following object / model pairs: stream objects in node models statistic wire objects in node models. From a modeling point of view, only some assignments of these constants have an effect. For instance, the interrupt method is ignored for streams with processor or queue sources, since these modules proactively set their own preference for interrupt method when sending packets. Also, the quiet interrupt method is ignored for statistic wires (the proper way to do this is to disable all triggers). Table Interrupt Method Symbolic Constants OPC_INTRPT_METHOD_FORCED OPC_INTRPT_METHOD_SCHED OPC_INTRPT_METHOD_QUIET End of Table MFA-1-96 Modeler/Release 10.0

97 The trigger symbolic constants listed below are used to specify which trigger flags are enabled on statistic wires. These constants can be assigned to the trigger attribute of statistics wire objects within node models. Since any combination of triggers is possible, each of the constants has a value which supports logical OR-ing of the constants to derive a composite value which can be assigned to an attribute. An example of this technique is shown in Figure Note that if the OPC_TRIG_HIGH_THRESH or OPC_TRIG_LOW_THRESH flags are enabled, the statistic wire object attributes high thresh or low thresh should be assigned appropriate values. Table Statistic Wire Trigger Symbolic Constants OPC_TRIG_RISING_EDGE OPC_TRIG_FALLING_EDGE OPC_TRIG_REPEAT OPC_TRIG_ZERO_CROSSING OPC_TRIG_HIGH_THRESH OPC_TRIG_LOW_THRESH End of Table Figure 1-10 Example Statistic Wire Trigger Attribute Assignment Ema_Object_Attr_Set (mid, obid, "trigger", COMP_CONTENTS, OPC_TRIG_RISING_EDGE OPC_TRIG_FALLING_EDGE OPC_TRIG_REPEAT, EMAC_EOL); The packet field type symbolic constants listed below are used to specify the type of a field within a packet format. These constants can be assigned to the type attribute of field objects within packet format models. Table Packet Field Type Symbolic Constants OPC_PKF_TYPE_INTEGER OPC_PKF_TYPE_FLOATING POINT OPC_PKF_TYPE_STRUCT OPC_PKF_TYPE_INFO OPC_PKF_TYPE_PACKET End of Table Modeler/Release 10.0 MFA-1-97

98 The packet encoding attribute symbolic constants listed below are used to specify the encoding within a packet format. These constants can be assigned to the encoding attribute of field objects within packet format models. Table Packet Encoding Attribute Symbolic Constants OPC_PKF_ENCODING_SIGNED_BIGE OPC_PKF_ENCODING_SIGNED_LITTLEE OPC_PKF_ENCODING_UNSIGNED_BIGE OPC_PKF_ENCODING_UNSIGNED_LITTLEE OPC_PKF_ENCODING_BIGE OPC_PKF_ENCODING_LITTLEE End of Table The ICI attribute type symbolic constants listed below are used to specify the type of an attribute within an ICI. These constants can be assigned to the type attribute of attribute descriptor objects within ICI format models. Table ICI Attribute Type Symbolic Constants OPC_ICA_TYPE_INTEGER OPC_ICA_TYPE_DOUBLE OPC_ICA_TYPE_STRUCT End of Table The cartographic line type symbolic constants listed below are used to specify what a line in a cartographic data set represents. These constants can be assigned to the type attribute of line objects within cartographic data sets. Four line types are supported: national boundary; coast, island, or lake; river; and internal boundary. Table Cartographic Line Type Symbolic Constants OPC_CDS_LINE_TYPE_NBOUND OPC_CDS_LINE_TYPE_COAST OPC_CDS_LINE_TYPE_RIVER OPC_CDS_LINE_TYPE_IBOUND End of Table MFA-1-98 Modeler/Release 10.0

99 The text size symbolic constants listed below are used to specify the size of text labels in cartographic data sets. These constants can be assigned to the text size attribute of cartographic objects (which are typically used as labels or to mark cities or other landmarks) within cartographic data sets. Table Text Size Symbolic Constants OPC_TEXT_SIZE_SMALL OPC_TEXT_SIZE_MEDIUM OPC_TEXT_SIZE_LARGE End of Table The interface description flags symbolic constants listed below are used to specify the options for an interface description. These constants can be assigned to the flags attribute of interface description objects. These flags map to the state of inheritance of limits, comments, default values, units, and value-restriction in symbol maps, in the interfaces for process, node, and link models. Table Interface Description Flags Symbolic Constants OPC_ID_INHRT_LIMS OPC_ID_INHRT_VAL_RESTRICT OPC_ID_INHRT_COMMENTS OPC_ID_INHRT_DEFVAL OPC_ID_INHRT_UNITS End of Table The properties object flags symbolic constants listed below are used to specify the options for a properties object. These constants can be assigned to the flags attribute of properties objects, and may be bitwise ORed to use more than one constant. In the OPNET node and process model domains these flags map to the functions of the Edit Model Attributes dialog box. The LOWLIM operations Modeler/Release 10.0 MFA-1-99

100 map to the From value, the HILIM operations map to the To value, DEFV_AUTOASSIGN maps to the Autoassign default value check box, and SYM_VAL_RESTRICT maps to the Allow other values check box for symbol maps. Table Properties Object Flags Symbolic Constants EMAC_LOWLIM_SET EMAC_LOWLIM_EXCLU EMAC_HILIM_SET EMAC_HILIM_EXCLU EMAC_DEFV_AUTOASSGN EMAC_SYM_VAL_RESTRICT End of Table The attribute assignment operation symbolic constants listed below are used to specify the type of operation for an attribute assignment. These constants can be assigned to the operation attribute of attribute assignment objects. In the OPNET model domain, the IGNORE operation maps to the promoted assignment, SET maps to set, and SUPPRESS maps to hidden. Table Attribute Assignment Operation Symbolic Constants OPC_AA_IGNORE OPC_AA_SET OPC_AA_SUPPRESS End of Table The output vector type symbolic constants listed below are used to specify whether an output vector is enumerated. These constants are assigned to the type attribute of the output vector object. If type is assigned the value OPC_OV_TYPE_VECTOR_ENUM, an output vector dictionary file must be specified in the enum dictionary attribute.. Table Output Vector Type Symbolic Constants OPC_OV_TYPE_VECTOR_DOUBLE OPC_OV_TYPE_VECTOR_ENUM End of Table MFA Modeler/Release 10.0

101 The output vector subelement type symbolic constants listed below are used to specify the subelement options for an output vector. These constants can be assigned to the type attribute of output vector objects. Objects of type OBJ_OV_VECTOR must have type values of either VECTOR_DOUBLE or ENUM. All other values can be used only with OBJ_OV_ELEMENT objects. Table Output Vector Subelement Type Symbolic Constants OPC_OV_TYPE_VECTOR_DOUBLE OPC_OV_TYPE_VECTOR_ENUM OPC_OV_TYPE_TOP_ELEMENT OPC_OV_TYPE_OBJECT OPC_OV_TYPE_STAT_GROUP OPC_OV_TYPE_STATISTIC End of Table The output vector drawing style symbolic constants listed below are used to specify the drawing style options for an output vector. These constants can be assigned to the drawing style attribute of output vector objects. Table Output Vector Drawing Style Symbolic Constants OPC_OV_DRAW_STYLE_SAMPHOLD OPC_OV_DRAW_STYLE_BAR OPC_OV_DRAW_STYLE_DISCRETE OPC_OV_DRAW_STYLE_LINEAR OPC_OV_DRAW_STYLE_SQR_WAVE OPC_OV_DRAW_STYLE_NONE End of Table Modeler/Release 10.0 MFA-1-101

102 The output vector threshold mode symbolic constants listed below are used to specify the threshold mode options for an output vector. These constants can be assigned to the threshold mode attribute of output vector objects. Table Output Vector Threshold Mode Symbolic Constants OPC_OV_THRESHOLD_MODE_NONE OPC_OV_THRESHOLD_MODE_GT OPC_OV_THRESHOLD_MODE_LT OPC_OV_THRESHOLD_MODE_GE OPC_OV_THRESHOLD_MODE_LE End of Table The output vector time unit symbolic constants listed below are used to specify the time unit options for an output vector. These constants can be assigned to the time unit attribute of output vector objects. Table Output Vector Time Unit Symbolic Constants OPC_OV_TIME_UNITS_SECONDS OPC_OV_TIME_UNITS_MONTHS OPC_OV_TIME_UNITS_GENERIC End of Table The self-description comparator symbolic constants listed below are used to specify the comparator value of a required self-description. These constants can be assigned to the comparator attribute of required self-description objects. Five types are supported: equals, one of, range, contains, and count. Table Self-Description Comparator Symbolic Constants OPC_SELFDESC_CMP_EQUALS OPC_SELFDESC_CMP_ONEOF OPC_SELFDESC_CMP_RANGE OPC_SELFDESC_CMP_CONTAINS OPC_SELFDESC_CMP_COUNT End of Table MFA Modeler/Release 10.0

103 The self-description assignment type symbolic constants listed below are used to specify the type value of an assigned self-description. These constants can be assigned to the type attribute of assigned self-description objects. Three types are supported: constant, characteristic, and value. Table Self-Description Assignment Type Symbolic Constants OPC_SELFDESC_ASSGN_CONST OPC_SELFDESC_ASSGN_CHARACTERISTIC OPC_SELFDESC_ASSGN_VALUE End of Table The project traffic growth time unit symbolic constants listed below are used to specify the time unit of traffic growth data. These constants can be assigned to the time units attribute of long term study (traffic growth) objects. Table Project Traffic Growth Time Unit Symbolic Constants OPC_PJ_TIME_UNITS_SECONDS OPC_PJ_TIME_UNITS_MINUTES OPC_PJ_TIME_UNITS_HOURS OPC_PJ_TIME_UNITS_DAYS OPC_PJ_TIME_UNITS_WEEKS OPC_PJ_TIME_UNITS_MONTHS OPC_PJ_TIME_UNITS_YEARS End of Table The project traffic growth result storage method symbolic constants listed below are used to specify the method used to store traffic growth data. These constants can be assigned to the result storage method attribute of long term study (traffic growth) objects. Table Project Traffic Growth Result Storage Method Symbolic Constants OPC_PJ_RESULT_STORE_EACH_SIMULATION OPC_PJ_RESULT_STORE_SUMMARY_ONLY End of Table Modeler/Release 10.0 MFA-1-103

104 The project traffic growth import options symbolic constants listed below are used to specify what to import during a long term study. These constants can be assigned to the import options attribute of long term study (traffic growth) objects. Table Project Traffic Growth Import Options Symbolic Constants OPC_PJ_IMPORT_NOTHING OPC_PJ_IMPORT_TRAFFIC OPC_PJ_IMPORT_NETWORK_AND_TRAFFIC End of Table The project traffic growth method symbolic constants listed below are used to specify the method used to calculate traffic growth. These constants can be assigned to the growth method attribute of long term study (traffic growth) objects. Table Project Traffic Growth Method Symbolic Constants OPC_PJ_GROWTH_REGULAR_SIMPLE OPC_PJ_GROWTH_REGULAR_COMPOUND OPC_PJ_GROWTH_SIMPLE_BY_TABLE OPC_PJ_GROWTH_COMPOUND_BY_TABLE End of Table The external system interface type symbolic constants listed below are used to specify the data type assigned to an external system interface. These constants can be assigned to the type attribute of esys interface objects. Table External System Interface Type Symbolic Constants (Part 1 of 2) OPC_ESYS_TYPE_INTEGER OPC_ESYS_TYPE_DOUBLE OPC_ESYS_TYPE_STRING OPC_ESYS_TYPE_BOOLEAN OPC_ESYS_TYPE_STDLOGIC OPC_ESYS_TYPE_BIT MFA Modeler/Release 10.0

105 Table External System Interface Type Symbolic Constants (Part 2 of 2) OPC_ESYS_TYPE_CHARACTER OPC_ESYS_TYPE_POINTER OPC_ESYS_TYPE_UNDEFINED End of Table The external system interface direction symbolic constants listed below are used to specify the data type assigned to an external system interface. These constants can be assigned to the direction attribute of esys interface objects. Table External System interface Direction Symbolic Constants OPC_ESYS_DIR_IN OPC_ESYS_DIR_OUT OPC_ESYS_DIR_INOUT OPC_ESYS_DIR_NC End of Table OPNET Model Construction Rules The previous three sections of this chapter present information on the objects, attributes, constants, and data type operators that can be defined via EMA to construct OPNET models. However, these sections have not presented the whole story, in that not every combination of objects that can be defined through EMA necessarily defines an OPNET model that makes sense. This section presents some guidelines for building OPNET models with EMA, as well as tips about potential errors, organized by model type. Network Model A subnet object named top must be defined. This object represents the environment that initially appears in the Project Editor. Subnets, nodes, and links must have their subnet attribute set, either to point to the top subnet object, or another created subnet object. Nodes that reference node models not present in the model directories will be ignored when read by the Project Editor, op_mksim, and the network simulation. Links and taps that reference transceiver modules that do not exist in the relevant node models will be ignored when read by the Project Editor, op_mksim, and the network simulation. Modeler/Release 10.0 MFA-1-105

106 Links and taps will be projected to the nearest icon edges of the nodes they reference when displayed by the Project Editor. Subnet, node, and link position coordinates should be specified in terms of the subnet grid unit, which is defined by the surrounding subnet s grid unit attribute. Node Model Compound value objects such as subqueues and channels must have at least one defined compound object (sub-object) that is assigned to their respective list attribute. Arbitrary coordinates may be assigned to modules via EMA, whereas modules created in the Node Editor are snapped to an invisible grid. Therefore, modules created by the Node Editor may not be able to align with modules previously created with EMA. It is possible to specify graphical positions and orientations for streams and statistics wires that do not correspond to their logical function in the node model. For instance, a connection from processor A to processor B can be specified so that it appears to run from processor A to processor C. This can lead to confusion and should be avoided. Values assigned to module attributes in EMA should be based on the units that appear in the attribute tables in Models, Objects, and Attributes on page MFA-1-26 (these are typically the same as those that appear in editor menus). For instance, the delay attribute of the duplex point-to-point link object has the units of seconds. Process Model Exactly one of the state objects must have the toggle attribute named initial enabled. Arbitrary coordinates may be assigned to states via EMA, whereas states created in the Process Editor are snapped to an invisible grid. Thus states created by the Process Editor may not be able to align with states previously created with EMA. It is possible to specify graphical positions and orientations for transitions that do no correspond to their logical function in the node model. For instance, a transition from an idle state to an active state can be specified so that it appears to be a transition from the idle state to itself. This can lead to confusion and should be avoided. External System Definition The simulator attribute for the external system object is required and is not promotable. MFA Modeler/Release 10.0

107 The direction indicates flow of data relative to the external simulator (that is, an Out interface receives data from the external simulator while an In interface sends data to the external simulator). The type attribute specifies the type of data that can be placed onto the interface. Using EMA The dimension attribute of interface objects refers to vector interfaces. The default value of zero means that the interface is not a vector interface. See Chapter 8 External System Domain on page MC-8-1 in the Modeling Concepts manual for more information about vector interfaces. The previous sections have introduced the EMA library functions, and the OPNET models, objects, attributes, and constants. This section presents the details of using EMA for model construction. Model Construction Figure 1-11 shows the typical sequence of operations involved in creating OPNET models with EMA. The file suffixes identify the different forms of the EMA application. The typical sequence is: 1) Write an application program in C or C++, invoking the correct EMA functions to create and write out an OPNET model. The file suffix of the application must be.em.c or.em.cpp, regardless of the model types read or written by the application so that the EMA compilation utility op_mkema will recognize the file as an EMA-based application. In this example, the application program is named y. Figure 1-11 Creating an EMA Application text editor (such as vi, emacs, or notepad) y.em.c or y.em.cpp application program (C or C++ form) 2) Compile the application program and bind it with the EMA library, using the op_mkema utility. This utility invokes a compiler defined by the comp_prog or comp_prog_cpp environment attribute (for C or C++, respectively), thereby generating an object code form of the application (with a.em.o suffix). The content of comp_flags or comp_flags_cpp is provided to the compiler. Next, op_mkema invokes the linker defined by the bind_static_prog environment attribute to combine the application object code and the EMA library into a final executable form (with a.em.x suffix). A full list of op_mkema options appears in op_mkema on page EI Note To use programs created by op_mkema on UNIX platforms, you must set the LD_LIBRARY_PATH environment variable manually. For information on setting the LD_LIBRARY_PATH environment variable, see UNIX Installation Troubleshooting on page AG-2-2 in the Administrator Guide. Modeler/Release 10.0 MFA-1-107

108 Figure 1-12 Compiling an EMA Application op_mkema y.em.c or y.em.cpp host C or C++ compiler y.em.o host linker (such as ld) y.em.x application program (C or C++ form) application program (object form) application program (executable form) libm3ema.so % op_mkema -m y EMA library (in <libdir>) 3) Run the executable form of the application program to create and write out one or more OPNET models, which can then be viewed using OPNET. In this example, a network model is created. Figure 1-13 Executing an EMA Application % y.em.x y.em.x process y.nt.m model file The shell command sequence in Figure 1-14 replays the preceding scenario for preparation of the y program and the model it produces. The y program generates an indication of the model it produced in this scenario; however, this is not automatically generated by the EMA library. Figure 1-14 Compilation of the EMA Application y % vi y.em.c % op_mkema -m y --- op_mkema issued the following command: --- /bin/sh -c cc -c \ /usr/opnet/op_models/y.em.c \ -I/usr/opnet/sys/include \ -o /usr/opnet/op_models/y.em.o \ > /usr/opnet/op_admin/tmp/cc_err 2>&1 --- op_mkema issued the following command: --- /bin/sh -c cc \ -o /usr/opnet/op_models/y.em.x \ /usr/opnet/op_models/y.em.o \ -L/usr/opnet/sys/sub_sparc_solaris/lib \ MFA Modeler/Release 10.0

109 -lema -lsup -lvos -lmdutl -lmdtab -lmdhndl -lobj -lorb -lprg\ -lsocket -lm -lc /usr/ucblib/libucb.a \ > /usr/opnet/op_admin/tmp/bind_err 2>& Ema executable program (y.em.x) produced % y.em.x Function Details Detailed descriptions of the functions follow. Modeler/Release 10.0 MFA-1-109

110 Ema_Init() Abstract: Syntax: Initializes the EMA package and configures it to use the specified operation mode(s). Ema_Init (mode, argc, argv) Argument Type Description mode int EMA operation mode flags [This value is a bitwise OR combination of the EMA operation mode symbolic constant flags listed in Table ] argc int number of command-line arguments with which the EMA program was invoked. [If no run-time arguments are provided to Ema_Init(), then argc must be set to 0.] argv char* [] pointer to an array of character s that contain the number of arguments specified in argc, one per. [If no run-time arguments are provided to Ema_Init(), then argv must be set to OPC_NIL.] Return Type: void no return value Details: This function initializes the internal data structures of the Ema package and must be invoked before any other EMA functions. There is no corresponding close function that needs to be called near the end of the EMA-based application. Because this function does not do any manipulations of models or objects, it is not considered an EMA operator. Operation Modes The Ema package can be initialized in one or more operation modes that specify diagnostic or release-oriented options. The set of modes that affect EMA is determined by the value of the argument passed to the Ema_Init() function. This argument can be any one of the operation mode symbolic constants described in Table 1-149, as well as a logical OR of several of these symbolic constants to produce a combination of the specified modes. For example, the following line shows Ema_Init() with error printing and diagnostic modes selected: Ema_Init (EMAC_MODE_ERR_PRINT EMAC_MODE_DIAG, argc, argv); MFA Modeler/Release 10.0

111 Table EMA Operation Modes If none of the modes are to be set, the symbolic constant EMAC_MODE_NONE should be passed to Ema_Init(). Operation Mode Constant EMAC_MODE_ERR_HALT EMAC_MODE_ERR_PRINT EMAC_MODE_DIAG EMAC_MODE_LIGHT_PRO PS EMAC_MODE_NONE EMAC_MODE_REL_<nn>, where <nn> = release number (23, 24, 25, 30, and so on) Mode Description This mode causes the Ema package to terminate the application program when it encounters an error condition. The termination is accompanied by an error message printed to the standard output device associated with the process. This mode is useful during the development phase of EMA-based applications, since errors in EMA calls are immediately and automatically made apparent. If this mode is not selected, error conditions in EMA calls will not directly cause the application program to terminate. Instead, the failing EMA function will simply return control to the invoking piece of code. This mode causes the Ema package to recover from an error condition, in addition to printing an error message to the standard output device associated with the process. It can be used in situations where the application program should inform the user that an error has occurred, but the program should not abort immediately. Because errors are printed to the standard output device, it's possible to redirect them into a log file. The error messages have a multi-line format, which indicates the application program name, the OPNET package involved (in this case, EMA), the function which failed, and the error condition causing the failure. This mode causes the Ema package to print out a diagnostic at each invocation of an EMA function by the application program. Printed s will include the name of the function that was called, and the fixed arguments which were passed to it (this mode does not support the printing of ACV lists passed to EMA operators). This mode is especially useful to review the logic of an application during debugging sessions, and to identify the location in a application program where an EMA error occurred. This mode specifies that, when models are read, properties objects are shared among attributes definition objects with the same properties. This mode gives you much lower memory usage, and can significantly improve performance of EMA programs, especially those dealing with network models. You can use this mode if you do not expect to modify properties objects. This mode specifies that no options are being given to EMA. This mode causes the Ema package to interpret arguments passed to EMA functions in the context of the EMA interface of a specified OPNET release. When this flag is not set, the context of the current release is the default. EMA-based application programs developed under a previous release should be modified to set this mode when invoking Ema_Init(), until they are fully converted to the current release EMA interface. This mode causes default values to be set for attributes that are new to the current release, and causes conversion of some attribute values. Some EMA attributes have different data types in different releases, and this mode indicates that assignments to these attributes are based on the data types of the specified release (although the data is internally stored and converted to the attribute data types of the current release). Data type conversion also applies when getting an attribute value in this mode. End of Table Modeler/Release 10.0 MFA-1-111

112 An error condition can be smoothly detected and dealt with by the application program, as an alternative to the error halt and error print modes. A global variable maintained by the Ema package is set to indicate success or failure after each invocation of an EMA function. This variable is named EmaS_Oper_Status, and it can be declared as an extern variable by having the EMA_EXT_DECS macro call within an EMA application program (after the preprocessor #include statements described later). The two values that can be taken on by the operation status variable represent success or failure, and these values are represented by the symbolic constants EMAC_COMPCODE_SUCCESS and EMAC_COMPCODE_FAILURE. In the cases where a failure has occurred, a one-line text message that describes the error is stored in another EMA global variable named EmaS_Error_Condition. This can be relayed to the user of the application program, or logged in some other fashion. The following example code fragment shows an Ema package function call, tests whether it succeeded, and prints out a message if an error occurred: Ema_Model_Read (MOD_PROBE, "sc_x1"); if (EmaS_Oper_Status == EMAC_COMPCODE_FAILURE) { printf ("Ema Error: %s\n", EmaS_Error_Condition); return -1; } Environment Attributes The Ema package requires access to some standard environment attributes to perform its task. Most importantly, the Ema package needs to know the locations of the model directories via the mod_dirs environment attribute, so that the Ema_Model_Read() and Ema_Model_Write() functions can respectively read and write OPNET model files. The Ema_Init() function obtains the values of environment attributes and stores them in Ema package global variables for use by all later Ema package function invocations. The environment database is the only source of environment attribute values for EMA applications; the other standard environment attribute sources (command line arguments, shell variables, and environment files) are not supported. EMA applications support the following environment attribute sets: Standard Environment Attributes (command-line only standard attributes are not supported) Diagnostic Environment Attributes User Lock Environment Attributes For more information on these attribute sets, see Chapter 2 Environment Attributes on page EI-2-1 of the External Interfaces manual. MFA Modeler/Release 10.0

113 In addition to the preceding attribute sets, EMA programs support one additional environment attribute: ema_verbose Specifies that EMA application code generated by Ema_Model_Code_Gen() should include assignments for all object attributes, even those attributes with default values. Non-verbose EMA application code only includes assignments for attributes that have non-default values. Data Type Default Value Boolean FALSE Modeler/Release 10.0 MFA-1-113

114 Ema_Model_Attr_Add() Abstract: Adds a user-defined attribute to the specified model. Syntax: Ema_Model_Attr_Add (model_id, attr_name, attr_properties) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. Use functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read() to obtain a model ID.] attr_name char* name of the new attribute attr_properties EmaT_Object_Id numeric object ID of the properties object for the attribute Return Type: void no return value Details: This function implements the attr_add operator for models. A user-defined attribute is an attribute defined by the user for model-specific purposes. EMA permits user-defined attributes to be added to any model type. However, only five OPNET model types support model attributes: base and derived node models, base and derived link models, and process models. Only these types of OPNET models will retain model attributes when written out by EMA. Attempts to add an attribute with a name that is identical to an existing attribute will fail, causing an error. MFA Modeler/Release 10.0

115 Ema_Model_Attr_Get() Abstract: Obtains the value of the specified object attributes. Syntax: Ema_Model_Attr_Get (model_id, <ACV_List>) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from several EMA functions.] <ACV_List> list of one or more ACV argument trios [Each ACV consists of three comma-separated arguments: a indicating the attribute name a symbolic constant or macro indicating the component a pointer to the memory location which will be filled by the value of the attribute This list must be terminated by the symbolic constant EMAC_EOL.] Return Type: void no return value Details: This function implements the attr_get operator for objects. A common use of this function is to get the number of objects in a model, as follows: Ema_Model_Attr_Get (<model_id>, ATTR_EMA_NUM_OBJECTS, COMP_OBTYPE(<object_type>), &<num_objs>, EMAC_EOL) where: <object_type> is the symbolic constant representing the object type within the model (such as OBJ_ND_PROCESSOR). These are listed in the tables following Models, Objects, and Attributes on page MFA <num_objs> is an integer Modeler/Release 10.0 MFA-1-115

116 Ema_Model_Attr_Nth() Abstract: Obtains the attribute name of the nth attribute of the specified model. Syntax: Ema_Model_Attr_Nth (model_id, index, attr_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model of interest index int numeric index of the attribute of interest name char* receives the name of the specified attribute; this value can then be used to call Ema_Model_Attr_Get() Return Type: VosT_Fun_Status The status of the operation (VOSC_SUCCESS or VOSC_FAILURE) Details: This function is useful as the method of obtaining the name of each attribute within loops that process all attributes of a specified model. The model ID is a numeric identifier that references a model. It can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read(). MFA Modeler/Release 10.0

117 Ema_Model_Attr_Print() Abstract: Syntax: Prints the contents of a single model attribute onto the standard output device. Ema_Model_Attr_Print (model_id, attr_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] attr_name char* name of the attribute-of-interest [The names of all model attributes are listed in the final section of this chapter.] Return Type: void no return value Details: Example output from this function appears below: * Attr Index: 0 * Attr Name: view subnet * Attr Type: set-required * Attr Defcon: no default contents * Attr Contents: Modeler/Release 10.0 MFA-1-117

118 Ema_Model_Attr_Set() Abstract: Syntax: Sets the value of the specified model attributes. Ema_Model_Attr_Set (model_id, <ACV_LIst>) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] <ACV_List> list of one or more ACV argument trios [Each ACV consists of three comma-separated arguments: a indicating the attribute name a symbolic constant or macro indicating the component a constant or variable which supplies the attribute value (the value type will correspond to the attribute type) This list must be terminated by the symbolic constant EMAC_EOL.] Return Type: void no return value Details: This function implements the attr_set operator for models. MFA Modeler/Release 10.0

119 Ema_Model_Base_Print() Abstract: Prints the contents of all existing EMA models within the invoking application onto the standard output device. The output is formatted into a hierarchical list of models, objects, and attributes. Syntax: Ema_Model_Base_Print () Argument Type Description no arguments Return Type: void no return value Details: The output format of this function appears below: <Model #0 Information> <Object #0 Information> <Attribute #0 Information> <...> <Object #1 Information> <Attribute #0 Information> <...> <Model #1 Information> <Object #0 Information> <...> Modeler/Release 10.0 MFA-1-119

120 Ema_Model_Code_Gen() Abstract: Syntax: Generates an EMA application source code file derived from the specified model. Ema_Model_Code_Gen (model_id, model_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model to be used as the basis for a new EMA application [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] model_name char* base name of generated EMA file [This name is used to create the name of the generated EMA file; the path to the file and file type suffix should not be included in this argument, since they will be automatically appended to generate the full file path. The generated file s type suffix is.em.c.] Return Type: void no return value Details: The logic of any algorithm used to define the specified model does not make it into the generated EMA application code. The generated code only creates an exact duplicate of the current state of the specified model, including all the objects and attribute values. The EMA application source code file is generated in the primary model directory. The value of the environment attribute ema_verbose affects the code generated by this function. If this environment attribute is set to TRUE, the generated EMA code will include assignments for all model and object attributes, even those with default values. The only way to set the ema_verbose environment attribute for detection by EMA applications is by a statement in the Environment Database (command-line arguments, shell variables, or environment files are not usable for EMA application environment attributes). MFA Modeler/Release 10.0

121 Ema_Model_Copy() Abstract: Syntax: Copies the specified EMA model. The duplicate model that results has an identical structure to the original and contains identical copies of each object in the original model. Ema_Model_Copy (model_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model to be copied [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] Return Type: EmaT_Model_Id numeric model ID of the new copy of the specified model Details: This function implements the copy operator for models. Modeler/Release 10.0 MFA-1-121

122 Ema_Model_Create() Abstract: Syntax: Creates an EMA model of the specified type. Ema_Model_Create (model_type) Argument Type Description model_type EmaT_Model_Type model type code Return Type: EmaT_Model_Id numeric model ID of the new model Details: This function implements the create operator for models. MFA Modeler/Release 10.0

123 Ema_Model_Destroy() Abstract: Syntax: Destroys the specified EMA model, deallocating the memory associated with all of its objects. Ema_Model_Destroy (model_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] Return Type: void no return value Details: This function implements the destroy operator for models. Modeler/Release 10.0 MFA-1-123

124 Ema_Model_Print() Abstract: Syntax: Prints the contents of the specified EMA model onto the standard output device. The output is formatted into a hierarchical list of objects and their attributes. Ema_Model_Print (model_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] Return Type: void no return value Details: The output format of this function appears below: <Model #0 Information> <Object #0 Information> <Attribute #0 Information> <Attribute #1 Information> <...> <Object #1 Information> <Attribute #0 Information> <Attribute #1 Information> <...> MFA Modeler/Release 10.0

125 Ema_Model_Read() Abstract: Syntax: Reads in the specified OPNET model file, creating a new model that can be manipulated within EMA. Ema_Model_Read (model_type, model_name) Argument Type Description model_type EmaT_Model_Typ e model type code model_name char* base name of model file to be read [This name references an OPNET model file that will be read in from a model directory; the path to the file and the file type suffix should not be included in this argument, since they will be automatically appended to generate the full file path.] Return Type: EmaT_Model_Id numeric model ID of the new model [The special value represented by the symbolic constant EMAC_NULL_MOD_ID will be returned if the read operation fails.] Details: This function implements the read operator for models. If the specified model file is not found, an error will occur within the function and will be handled according to the current EMA error mode. Modeler/Release 10.0 MFA-1-125

126 Ema_Model_Write() Abstract: Syntax: Writes the specified EMA model out as a model file within the primary model directory. Ema_Model_Write (model_id, model_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] model_name char* base name of model file to be written [This name references an OPNET model file that will be written to the primary model directory; the path to the file and the file type suffix should not be included in this argument, since they will be automatically appended to generate the full file path.] Return Type: EmaT_Compcode Completion code indicating whether the write operation completed successfully [This code can be compared to the two symbolic constants EMAC_COMPCODE_SUCCESS and EMAC_COMPCODE_FAILURE.] Details: This function implements the write operator for models. If the specified model file cannot be written, an error will occur within the function and will be handled according to the current EMA error mode. MFA Modeler/Release 10.0

127 Ema_Object_Attr_Add() Abstract: Syntax: Adds a user-defined attribute to the specified object. Ema_Object_Attr_Add (model_id, object_id, attr_name, attr_properties) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from several EMA functions.] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from several EMA functions.] attr_name char* name of the new attribute attr_properties EmaT_Object_Id numeric object ID of the properties object for the attribute Return Type: void no return value Details: This function implements the attr_add operator for objects. A user-defined attribute is an attribute defined by the user for model-specific purposes. EMA permits object attributes to be added to any object type. Attempts to add an attribute with a name that is identical to an existing attribute will fail, causing an error. Modeler/Release 10.0 MFA-1-127

128 Ema_Object_Attr_Get() Abstract: Syntax: Obtains the value of the specified object attributes. Ema_Object_Attr_Get (model_id, object_id, <ACV_List>) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from several EMA functions.] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from several EMA functions.] <ACV_List> list of one or more ACV argument trios [Each ACV consists of three comma-separated arguments: a indicating the attribute name a symbolic constant or macro indicating the component a pointer to the memory location that will be filled by the value of the attribute This list must be terminated by the symbolic constant EMAC_EOL.] Return Type: void no return value Details: This function implements the attr_get operator for objects. MFA Modeler/Release 10.0

129 Ema_Object_Attr_Nth() Abstract: Syntax: Obtains the attribute name of the nth attribute of the specified object. Ema_Object_Attr_Nth (model_id, object_id, index, attr_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model containing the object of interest object_id EmaT_Object_Id numeric object ID of the object of interest index int numeric index of the attribute of interest attr_name char* character buffer that receives the name of the specified attribute; this buffer may then be used in a call to Ema_Object_Attr_Get() Return Type: VosT_Fun_Status The status of the operation (VOSC_SUCCESS or VOSC_FAILURE) Details: This function is useful as the method of obtaining the name of each attribute within loops that process all attributes of a specified object. The model ID is a numeric identifier that references a model. It can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read(). The object ID is a numeric identifier that references an object. It can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth(). You should ensure that the buffer referenced by attr_name* is large enough to hold the attribute name; otherwise the resulting application may abort with a segmentation violation. Modeler/Release 10.0 MFA-1-129

130 Ema_Object_Attr_Print() Abstract: Syntax: Prints the contents of a single object attribute onto the standard output device. Ema_Object_Attr_Print (model_id, object_id, attr_name) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] attr_name char* name of the attribute-of-interest [The names of all model attributes are listed in the final section of this chapter.] Return Type: void no return value Details: Example output from this function appears below: * Attr Index: 0 * Attr Name: name * Attr Type: set-required * Attr Defcon: no default contents * Attr Contents: arbitrator MFA Modeler/Release 10.0

131 Ema_Object_Attr_Set() Abstract: Syntax: Sets the value of the specified object attributes. Ema_Object_Attr_Set (model_id, object_id, <ACV_List>) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from several EMA functions.] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from several EMA functions.] <ACV_List> list of one or more ACV argument trios [Each ACV consists of three comma-separated arguments: a indicating the attribute name a symbolic constant or macro indicating the component a constant or variable which supplies the attribute value (the value type will correspond to the attribute type) This list must be terminated by the symbolic constant EMAC_EOL.] Return Type: void no return value Details: This function implements the attr_set operator for objects. Modeler/Release 10.0 MFA-1-131

132 Ema_Object_Copy() Abstract: Syntax: Copies the specified object. The duplicate object that results has an identical structure to the original and contains identical values for each attribute (except those of type OBJECT_ID). Ema_Object_Copy (model_id, object_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object to be copied [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] Return Type: EmaT_Object_Id numeric object ID of the new object Details: This function implements the copy operator for objects. Attributes of type OBJECT_ID will not be set to any value in the duplicate object. It is the caller's responsibility to set the values of these attributes and, if necessary, to copy the objects referred to by these attributes. MFA Modeler/Release 10.0

133 Ema_Object_Create() Abstract: Syntax: Creates an object of the specified type within the specified EMA model. Ema_Object_Create (model_id, object_type) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_type EmaT_Object_Typ e object type code Return Type: EmaT_Object_Id numeric object ID of the new object Details: This function implements the create operator for objects. Modeler/Release 10.0 MFA-1-133

134 Ema_Object_Destroy() Abstract: Syntax: Destroys the specified object, deallocating its associated memory. Ema_Object_Destroy (model_id, object_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] Return Type: void no return value Details: This function implements the destroy operator for objects. MFA Modeler/Release 10.0

135 Ema_Object_Move() Abstract: Syntax: Moves the specified object from the source model into the destination model. Ema_Object_Move (src_model_id, object_id, dst_model_id) Argument Type Description src_model_id EmaT_Model_Id numeric model ID of the model that originally contains the specified object [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object to be moved [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] dst_model_id EmaT_Model_Id numeric model ID of the model to which the specified object will be moved Return Type: EmaT_Object_Id numeric object ID of the moved object within the destination model Details: This function implements the move operator for objects. Once moved into the destination model, the specified object is assigned a new object ID, which will generally be different than its original ID (the new object ID is returned as the value of this function). This function moves only the specified object. To move the object and all of its sub-objects, use Ema_Object_Move_Recursively(). Modeler/Release 10.0 MFA-1-135

136 Ema_Object_Move_Recursively() Abstract: Syntax: Moves the specified object and all of its sub-objects from the source model into the destination model. Ema_Object_Move_Recursively (src_model_id, object_id, dst_model_id) Argument Type Description src_model_id EmaT_Model_Id numeric model ID of the model that originally contains the specified object [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object to be moved [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] dst_model_id EmaT_Model_Id numeric model ID of the model to which the specified object will be moved Return Type: EmaT_Object_Id numeric object ID of the moved object within the destination model Details: This function works like Ema_Object_Move(), except that it also moves all sub-objects of the specified object. Because properties objects will be moved as well, this function should only be used with Ema_Props_Sharing_Set (VOSC_FALSE) and Ema_Equal_Props_Sharing_Set (VOSC_FALSE). If the properties are shared, they should be replicated instead of moved. MFA Modeler/Release 10.0

137 Ema_Object_Nth() Abstract: Obtains the object ID of the nth object of the specified type. Syntax: Ema_Object_Nth (model_id, object_type, n) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_type EmaT_Object_Type object type code of the object-of-interest n int numeric index of the object-of-interest Return Type: EmaT_Object_Id numeric object ID of the specified object, or EMAC_NULL_OBJ_ID if an error occurs Details: This function implements the nth operator for objects. This function is useful within loops that process all objects of a particular type, as the method of obtaining the object ID of each object. This function is often used with code that gets the number of objects in the model, as shown in the Details section for Ema_Model_Attr_Get(). Modeler/Release 10.0 MFA-1-137

138 Ema_Object_Print() Abstract: Syntax: Prints the contents of the specified object onto the standard output device. The output is formatted into a list of the object s attributes. Ema_Object_Print (model_id, object_id) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from the functions Ema_Model_Create(), Ema_Model_Copy(), or Ema_Model_Read().] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from the functions Ema_Object_Create(), Ema_Object_Copy(), Ema_Object_Move(), Ema_Object_Move_Recursively(), or Ema_Object_Nth().] Return Type: void no return value Details: Example output from this function appears below: * Object ID: #0 * Object Type: queue * Object Index: * Attr Index: 0 * Attr Name: name * Attr Type: set-required * Attr Defcon: no default contents * Attr Contents "mac" * Attr Index: 1 * Attr Name: subqueue count * Attr Type: integer * Attr Defcon: 1 * Attr Contents < > MFA Modeler/Release 10.0

139 Ema_Object_Prom_Attr_Set() Abstract: Syntax: Defines the properties of a promoted attribute expected from a lower-level model or object. Ema_Object_Prom_Attr_Set (model_id, object_id, attr_name, attr_properties) Argument Type Description model_id EmaT_Model_Id numeric model ID of the model-of-interest [This value is a numeric identifier that references a model. A model ID can be obtained from several EMA functions.] object_id EmaT_Object_Id numeric object ID of the object-of-interest [This value is a numeric identifier that references an object. An object ID can be obtained from several EMA functions.] attr_name char* name of the promoted attribute attr_properties EmaT_Object_Id numeric object ID of the properties object for the attribute Return Type: void no return value Details: This function implements the prom_attr_set operator for objects. Setting a value for a promoted attribute via this function is different from setting the promote component of an attribute via Ema_Object_Attr_Set(). Setting an object attribute s promote component to 1 causes that attribute to be promoted to a higher level object. Ema_Object_Prom_Attr_Set() defines the properties for an attribute that is expected to be promoted from a lower level; however, it does not actually set the value for the promoted attribute. You must call Ema_Object_Attr_Set() after calling Ema_Object_Prom_Attr_Set() to actually set the attribute s value. Within OPNET editors or a simulation, if an object has values set for promoted attributes, and these attributes do not match attributes actually promoted from lower-level models or objects, the set values are discarded and an error message occurs. Because this function allocates a storage cell to hold a value for a promoted attribute, it should only be called once for a particular object s attribute; repeated calls to set the same promoted attribute on an object will cause an error. However, once a promoted attribute has been set using this function, its value can be queried by Ema_Object_Attr_Get() and modified by Ema_Object_Attr_Set(), just as if it were a built-in attribute. Modeler/Release 10.0 MFA-1-139

140 Ema_Ov_File_Placement_Mode_Set() Abstract: Syntax: Specifies where OV files should be saved. Ema_Ov_File_Placement_Mode_Set (setting) Argument Type Description setting int placement flag (see Details) Return Type: void no return value Details: This function specifies where OV files should be placed when written to disk. If setting is OPC_TRUE, OV files are saved to the same directory as the network model file with the same name (excluding suffixes), if any. If such a network model file doesn t exist, or if setting is OPC_FALSE (the default), OV files are saved to the user s default model directory. MFA Modeler/Release 10.0