包概述
Output Table 包为开发者提供了一种机制,用于持久存储和检索表格格式的数据。多个表可以存储在一个用户命名的 OT 文件中,该文件带有 .ot 扩展名。
OT 文件可以与项目场景关联。在这种情况下,核心软件确保该文件随其关联的项目一起应对场景的重命名和删除。OT 文件被视为输入文件,因此在复制场景时也会被一并复制。
术语
Output Table 包使用以下术语:
table data
以行和列存储的(数值或字符串)数据。
table template
对组成输出表的各列的描述。每一列都关联一个唯一的标签。每个表对应一个模板。
table cell
构成表的组件。每个单元格由列标签和行号指定。表单元格可以包含字符串或数值信息(或其数组),并可选地包含热链接(hotlink)。
hotlink
对外部实体的引用,可以是一个网络对象(如节点或链路)、另一个表(此时该热链接通常称为 drilldown),或某个对象的属性。
用法
以下过程给出了使用 OT 文件的一般步骤。
过程 1:向 OT 文件写入数据
-
使用 Oma_Ot_Writer_Open() 打开 OT 文件,该函数以文件名作为其参数。使用 Oma_Ot_Writer_Network_Model_Name_Set() 将该文件与项目的场景关联。
-
指定表的模板:
- 2.1 使用 Oma_Ot_Writer_Template_Add() 创建新模板。
- 2.2 使用 Oma_Ot_Template_Column_Add() 向模板添加列。
-
使用 Oma_Ot_Writer_Table_Add() 创建表。
-
使用 Oma_Ot_Table_Cell_Value_Set()(单个值)和 Oma_Ot_Table_Cell_Value_Array_Set()(值数组)设置表的单元格值。
- 如果某个单元格热链接到网络对象,使用 Oma_Ot_Hot_Link_Create() 创建热链接,并使用 Oma_Ot_Hot_Link_Object_Set() 指定该对象。然后使用 Oma_Ot_Table_Cell_Hot_Link_Set() 设置单元格的热链接。记得使用 Oma_Ot_Hot_Link_Destroy() 释放与热链接关联的内存。
- 表的数据按行逐行指定。一行的所有数据指定完毕后,需要使用 Oma_Ot_Table_Row_Write() 提交(存储到文件中)。
- 写入过程中行不支持随机访问。也就是说,你不能回头修改已提交行中的数据。行按顺序提交:你不能先提交第 3 行和第 5 行,然后再提交第 4 行。
-
当所有行都写入表后,调用 Oma_Ot_Table_Write_Complete() 释放未使用的表内存。
-
对要存储在 OT 文件中的每个表重复步骤 2–5。完成后,使用 Oma_Ot_Writer_Close() 关闭 OT 文件,该函数同时会销毁关联的模板和表。
过程 1 结束
过程 2:从 OT 文件读取数据
-
使用 Oma_Ot_Reader_Open() 打开 OT 文件。
-
如果想在读取表时抑制进度条显示,或使用自定义进度显示,先使用 Oma_Ot_Progress_Proc_Get() 保存当前的进度条过程,然后调用 Oma_Ot_Progress_Proc_Set()。
-
检索所需的表:
- 如果只需要特定的表,使用 Oma_Ot_Reader_Table_Get() 检索该表。
- 如果需要所有符合某一条件的表,使用 Oma_Ot_Reader_Iterator_Create() 及相关的
Oma_Ot_Reader_Iterator…函数检索这些表。
-
使用 Oma_Ot_Table_Template_Get() 检索表的模板,并使用
Oma_Ot_Table_Template…函数检索表各列的属性。 -
使用 Oma_Ot_Table_Cell_Value_Get() 及相关函数检索表的数据。
-
读取完某个表的数据后,使用 Oma_Ot_Table_Destroy() 关闭该表。
注意: 如果打算让 OT reader 保持打开状态一段不确定的时间,较好的做法是使用 Oma_Ot_Reader_Detach() 分离该文件。这可以降低计算机耗尽文件描述符的可能性。文件处于打开但已分离的状态时,仍驻留在内存中,你可以继续使用 Oma_Ot_Table_Cell_Value_Get() 及相关函数。
-
如有必要,使用 Oma_Ot_Progress_Proc_Set() 恢复之前的进度条过程。
-
读完所有所需的表后,使用 Oma_Ot_Reader_Close() 关闭 OT reader。
注意: 即使关闭了 OT reader,你仍然可以访问输出表。无论 reader 是否仍然打开,用完表之后都必须将其销毁;否则,为该表预留的内存将会泄漏。
过程 2 结束