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