包概述

prg_log 包提供了一套通用 API,用于创建日志并生成 Modeler 日志查看器能够解释的格式的日志条目。日志条目可以由仿真生成(使用 op_prg_log… 内核过程),也可以由 Modeler 自身生成(例如在流分析等耗时较长的操作期间)。

ETS 的“Log Package“(第 640 页)提供了一套用于打开日志查看器以显示日志内容的 API。

一个日志由一个 tfile 目录(命名为 <log name>.olf.dir))及其内容组成。日志目录包含两类文件:

  • 一个 log_info 文件
  • 数据(*.ot)文件

log_info 文件是一个文本文件,包含有关日志的信息,包括日志选项、所维护数据文件的列表以及日志句柄的列表。数据文件是二进制 OT(输出表)文件,包含日志的模板定义和若干条日志条目。

日志存储(log store) 就是一个具体的日志。可以使用 prg_log_open() 打开一个已有日志或创建新日志,从而获得日志存储句柄。

可以把日志看作数据表。日志中的每类信息是一列,每条日志条目是对应日志各列的一组值的行。日志中的各列构成该日志的模板。可以使用 prg_log_template_exists() 判断已打开的日志是否具有模板。要创建模板,需使用 prg_log_column_add() 向日志添加列。每列都有名称和数据类型。列可以依赖于另一列,从而在表内形成层次结构。使用 prg_log_column_child_dependency_add() 定义这种层次结构。

可以使用 prg_log_write() 向日志写入条目。条目会被保存到数据文件中。数据文件所能容纳的条目数有上限,达到上限后会打开新的数据文件。使用 prg_log_max_file_rows_set() 可设置该值。此外,可以使用 prg_log_max_log_rows_set() 指定日志所维护条目数的最大值。为实现这一最大值,日志将其数据文件视为滚动缓冲区;条目数超过最大值的老数据文件被视为不再维护。可以使用 prg_log_old_files_delete() 删除这些老文件。

日志句柄(log handle) 是向日志写入的一种简化方式。使用 prg_log_handle_generate(),可以创建一个日志句柄,为日志的选定列预定义值(例如特定的类别和严重级别)。之后,当需要用这些类别和严重级别的值记录日志条目时,就可以配合该日志句柄使用 prg_log_handle_write()。在调用中,只需为那些未在日志句柄中预定义的列指定值。可以使用 prg_log_handle_valid() 验证日志句柄,并使用 prg_log_handle_destroy() 销毁不再需要的日志句柄。

可以使用 prg_log_tfile_assoc() 将日志与某个 tfile(如特定场景)关联。要将日志内容导出到文本文件,使用 prg_log_text_export()。日志使用完毕后,既可以使用 prg_log_close() 将其关闭以备后用,也可以使用 prg_log_delete() 将其文件彻底删除。