Ema_Init()
Abstract
Initializes the EMA package and configures it to use the specified operation mode(s).
Syntax
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 167.] |
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 strings that contain the number of arguments specified in argc, one per string. [If no run-time arguments are provided to Ema_Init(), then argv must be set to OPC_NIL.] |
Return Type
void
No return value.
Header
ema.h
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.
WARNING: Do not use the FIN, FOUT, and FRET macros in the main() function of an EMA program. An abnormal function stack imbalance error will occur if these macros occur before Ema_Init() has been invoked.
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 167, 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);
If none of the modes are to be set, the symbolic constant EMAC_MODE_NONE should be passed to Ema_Init().
Table 167: EMA Operation Modes
| Operation Mode Constant | Mode Description |
|---|---|
EMAC_MODE_ERR_HALT |
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. |
EMAC_MODE_ERR_PRINT |
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 that indicates the application program name, the API package involved (in this case, EMA), the function which failed, and the error condition causing the failure. |
EMAC_MODE_DIAG |
This mode causes the Ema package to print out a diagnostic string at each invocation of an EMA function by the application program. Printed strings 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. |
EMAC_MODE_LIGHT_PROPS |
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. |
EMAC_MODE_NONE |
This mode specifies that no options are being given to EMA. |
EMAC_MODE_REL_<nn>, where <nn> = release number (23, 24, 25, 30, and so on) |
This mode causes the Ema package to interpret arguments passed to EMA functions in the context of the EMA interface of a specified 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. |
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 string 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;
}
Preferences
The Ema package requires access to some standard preferences to perform its task. Most importantly, the Ema package needs to know the locations of the model directories via the mod_dirs preference, so that the Ema_Model_Read() and Ema_Model_Write() functions can respectively read and write Riverbed model files. The Ema_Init() function obtains the values of preferences and stores them in Ema package global variables for use by all later Ema package function invocations. The preferences file is the only source of preference values for EMA applications; the other standard preference sources (command line arguments, shell variables, and environment files) are not supported.
EMA applications support the following preference sets:
- Standard Preferences (command-line only standard attributes are not supported)
- Diagnostic Preferences
- User Lock Preferences
For more information on these preference sets, see Chapter 2 “Preferences” on page 31.
In addition to the preceding preference sets, EMA programs support one additional preference:
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:
Boolean - Default Value:
FALSE