Package Overview

The Output Table package provides developers with a mechanism to persistently store and retrieve data that is in a tabular format. Multiple tables can be stored in a user-named OT file, having the .ot extension.

An OT file can be linked to a project scenario. In this case, the core software ensures that the file stays with its associated project with respect to scenario renamings and deletions. OT files are treated as inputs and thus are among the files copied when a scenario is duplicated.

Terminology

The Output Table package uses the following terms:

table data

(numeric or string) stored in rows and columns.

table template

Description of the columns that comprise an output table. Each column has a unique tag associated with it. There is one template per table.

table cell

Components that make up the table. Each cell is specified by the column tag and row number. Table cells can contain string or numeric information or arrays of such information, and optionally hotlinks.

hotlink

A reference to an external entity, which could be a network object (such as a node or link), another table (in which case, the hotlink is commonly referred to as a drilldown), or an object's attribute.

Usage

The following procedures give general steps for using OT files.

Procedure 1: Writing Data to an OT File

  1. Open the OT file using Oma_Ot_Writer_Open(), which takes the file name as its argument. Use Oma_Ot_Writer_Network_Model_Name_Set() to associate the file with a project's scenario.

  2. Specify the table's template:

  3. Create the table using Oma_Ot_Writer_Table_Add().

  4. Set the table's cell values using Oma_Ot_Table_Cell_Value_Set() (for individual values) and Oma_Ot_Table_Cell_Value_Array_Set() (for an array of values).

    • If a particular cell hotlinks to a network object, create the hotlink using Oma_Ot_Hot_Link_Create() and specify the object using Oma_Ot_Hot_Link_Object_Set(). Then set the cell's hotlink using Oma_Ot_Table_Cell_Hot_Link_Set(). Remember to use Oma_Ot_Hot_Link_Destroy() to free the memory associated with the hotlink.
    • The table's data is specified on a row-by-row basis. After all the data for a row has been specified, it needs to be committed (stored in the file) using Oma_Ot_Table_Row_Write().
    • Rows are not random access during the writing process. That is, you cannot go back and alter data in a committed row. Rows are committed sequentially: you cannot commit row 3 and 5 and then commit 4.
  5. When all rows have been written to the table, free unused table memory by calling Oma_Ot_Table_Write_Complete().

  6. Repeat steps 2–5 for each table you want to store in the OT file. When done, close the OT file using Oma_Ot_Writer_Close(), which will also destroy the associated templates and tables.

End of Procedure 1

Procedure 2: Reading Data from an OT File

  1. Open the OT file using Oma_Ot_Reader_Open().

  2. If you want to suppress the progress bar display when reading the tables or use a custom progress display, store the current progress bar procedure using Oma_Ot_Progress_Proc_Get(). Then call Oma_Ot_Progress_Proc_Set().

  3. Retrieve the desired table:

  4. Retrieve the table's template using Oma_Ot_Table_Template_Get() and use the Oma_Ot_Table_Template… functions to retrieve the properties of the table's columns.

  5. Retrieve the table's data using Oma_Ot_Table_Cell_Value_Get() and related functions.

  6. When you are finished reading data from a table, close it using Oma_Ot_Table_Destroy().

    Note: If you plan to keep the OT reader open for an indeterminate period, it is good practice to detach the file using Oma_Ot_Reader_Detach(). This reduces the possibility that the computer will run out of file descriptors. When the file is open but detached, it still resides in memory and you can continue to use Oma_Ot_Table_Cell_Value_Get() and related functions.

  7. If necessary, restore the previous progress bar procedure using Oma_Ot_Progress_Proc_Set().

  8. After all required tables have been read, close the OT reader using Oma_Ot_Reader_Close().

Note: You can access an output table even after you close the OT reader. Whether or not the reader is still open, you must destroy the table when you are finished with it; otherwise, the memory reserved for that table will be leaked.

End of Procedure 2

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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