Ema_Init()

摘要

初始化 EMA 包,并将其配置为使用指定的操作模式。

语法

Ema_Init (mode, argc, argv)
参数 类型 说明
mode int EMA 操作模式标志 [该值是 表 167 中所列 EMA 操作模式符号常量标志的按位 OR 组合。]
argc int 调用 EMA 程序时附带的命令行参数个数。[如果没有向 Ema_Init() 提供运行时参数,则 argc 必须设为 0。]
argv char* [ ] 指向字符字符串数组的指针,该数组包含 argc 所指定数量的参数,每个字符串对应一个参数。[如果没有向 Ema_Init() 提供运行时参数,则 argv 必须设为 OPC_NIL。]

返回类型

void

无返回值。

头文件

ema.h

详情

该函数初始化 Ema 包的内部数据结构,必须在任何其他 EMA 函数之前调用。不存在需要在基于 EMA 的应用程序接近结束时调用的对应“close”函数。由于该函数不对模型或对象进行任何操作,因此不将其视为 EMA 操作符。

**警告:**不要在 EMA 程序的 main() 函数中使用 FIN、FOUT 和 FRET 宏。如果这些宏出现在 Ema_Init() 被调用之前,将发生异常函数栈不平衡错误。

操作模式

Ema 包可以在一种或多种操作模式下初始化,这些模式指定诊断类或面向版本发布的选项。影响 EMA 的模式集合由传递给 Ema_Init() 函数的参数的值决定。该参数可以是 表 167 中描述的操作模式符号常量之一,也可以是若干符号常量的逻辑 OR,以产生指定模式的组合。例如,下面一行展示了选择了错误打印模式和诊断模式的 Ema_Init():

	Ema_Init (EMAC_MODE_ERR_PRINT | EMAC_MODE_DIAG, argc, argv);

如果不需要设置任何模式,应向 Ema_Init() 传递符号常量 EMAC_MODE_NONE。

表 167:EMA 操作模式

操作模式常量 模式说明
EMAC_MODE_ERR_HALT 该模式使 Ema 包在遇到错误条件时终止应用程序。终止的同时会向与该进程关联的标准输出设备打印一条错误消息。该模式在基于 EMA 的应用程序的开发阶段很有用,因为 EMA 调用中的错误会立即且自动地显现出来。如果不选择该模式,EMA 调用中的错误不会直接导致应用程序终止;取而代之,失败的 EMA 函数只是将控制权返回给发起调用的代码。
EMAC_MODE_ERR_PRINT 该模式使 Ema 包从错误条件中恢复,并向与该进程关联的标准输出设备打印一条错误消息。它适用于这样的场合:应用程序应当通知用户发生了错误,但程序不应立即中止。由于错误被打印到标准输出设备,可以将它们重定向到日志文件。错误消息采用多行格式,指明应用程序名称、涉及的 API 包(此处为 EMA)、失败的函数以及导致失败的错误条件。
EMAC_MODE_DIAG 该模式使 Ema 包在应用程序每次调用 EMA 函数时打印一条诊断字符串。打印的字符串将包括被调用函数的名称以及传递给它的固定参数(该模式不支持打印传递给 EMA 操作符的 ACV 列表)。该模式在调试会话中复查应用程序的逻辑、以及定位 EMA 错误在应用程序中出现的位置时特别有用。
EMAC_MODE_LIGHT_PROPS 该模式指定,在读取模型时,properties 对象在具有相同 properties 的属性定义对象之间共享。该模式可大幅降低内存用量,并能显著提升 EMA 程序的性能,尤其是处理网络模型的程序。如果不打算修改 properties 对象,就可以使用该模式。
EMAC_MODE_NONE 该模式指定不给 EMA 提供任何选项。
EMAC_MODE_REL_<nn>,其中 <nn> = 版本号(23、24、25、30 等) 该模式使 Ema 包在指定版本的 EMA 接口上下文中解释传递给 EMA 函数的参数。如果不设置该标志,则默认使用当前版本的上下文。在先前版本下开发的基于 EMA 的应用程序,在其完全转换到当前版本 EMA 接口之前,应当在调用 Ema_Init() 时设置该模式。该模式会为当前版本新增的属性设置默认值,并导致某些属性值的转换。某些 EMA 属性在不同版本中具有不同的数据类型,该模式表明对这些属性的赋值基于指定版本的数据类型(尽管数据在内部存储并转换为当前版本的属性数据类型)。在该模式下获取属性值时同样适用数据类型转换。

作为错误终止和错误打印模式的替代方案,应用程序可以平滑地检测并处理错误条件。Ema 包维护一个全局变量,在每次 EMA 函数调用后被设置为指示成功或失败。该变量名为 EmaS_Oper_Status,可以通过在 EMA 应用程序中调用 EMA_EXT_DECS 宏(在稍后描述的预处理器 #include 语句之后)将其声明为 extern 变量。

操作状态变量可取的两个值代表成功或失败,这两个值由符号常量 EMAC_COMPCODE_SUCCESS 和 EMAC_COMPCODE_FAILURE 表示。在发生失败的情况下,一段描述该错误的单行文本消息会存储在另一个名为 EmaS_Error_Condition 的 EMA 全局变量中。该字符串可以传达给应用程序的用户,或者以其他方式记录。

下面的示例代码片段展示了一次 Ema 包函数调用、测试其是否成功,并在发生错误时打印一条消息:

Ema_Model_Read (MOD_PROBE, "sc_x1");
if (EmaS_Oper_Status == EMAC_COMPCODE_FAILURE)
	{
	printf ("Ema Error: %s\n", EmaS_Error_Condition);
	return -1;
	}

首选项

Ema 包需要访问某些标准首选项才能完成其任务。最重要的是,Ema 包需要通过 mod_dirs 首选项知道模型目录的位置,以便 Ema_Model_Read() 和 Ema_Model_Write() 函数分别读取和写入 Riverbed 模型文件。Ema_Init() 函数获取各首选项的值并将它们存储在 Ema 包的全局变量中,供后续所有 Ema 包函数调用使用。首选项文件是 EMA 应用程序首选项值的唯一来源;其他标准首选项来源(命令行参数、shell 变量和环境文件)不受支持。

EMA 应用程序支持以下首选项集:

  • 标准首选项(Standard Preferences,不支持仅限命令行的标准属性)
  • 诊断首选项(Diagnostic Preferences)
  • 用户锁首选项(User Lock Preferences)

有关这些首选项集的更多信息,参见第 2 章“Preferences”第 31 页。

除上述首选项集之外,EMA 程序还支持一个附加首选项:

ema_verbose

指定由 Ema_Model_Code_Gen() 生成的 EMA 应用程序代码应当包含所有对象属性的赋值,即使这些属性具有默认值。非 verbose 的 EMA 应用程序代码只包含具有非默认值的属性的赋值。

  • 数据类型:Boolean
  • 默认值:FALSE

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

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

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

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