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