Package Overview
The prg_log package provides a common API to create logs and generate log entries in a format that the Modeler log viewer can interpret. Entries can be generated by the simulation (using the op_prg_log… Kernel Procedures) or by Modeler itself (for example, during lengthy operations such as flow analysis).
The ETS “Log Package“ on page 640 provides an API for opening log viewers to display the contents of a log.
A log consists of a tfile directory (named <log name>.olf.dir)) and its contents. The log directory contains two kinds of files:
- A
log_infofile - Data (
*.ot) files
The log_info file is a text file that contains information about the log, including log options, a list of maintained data files, and a list of log handles. The data files are binary OT (output table) files that contain the log’s template definition and some number of log entries.
A log store is a specific log. You can obtain a log store handle by using prg_log_open() to open an existing log or create a new one.
Logs can be thought of as tables of data. Each kind of information in the log is a column. Each log entry is a row of values corresponding to the log’s columns. The columns in a log comprise that log’s template. You can determine whether a log you’ve opened has a template with prg_log_template_exists(). To create a template, you add columns to the log with prg_log_column_add(). Each column has a name and a data type. Columns can be dependent on another column, forming a hierarchy within the table. Use prg_log_column_child_dependency_add() to define this hierarchy.
You can write an entry to a log with prg_log_write(). The entry is saved to a data file. Data files have a maximum number of entries they can hold, after which a new data file is opened. To set this value, use prg_log_max_file_rows_set(). In addition, you can specify a maximum number of entries to be maintained by a log, with prg_log_max_log_rows_set(). To implement this maximum, the log treats its data files as a rolling buffer; old data files whose entries exceed the maximum are considered unmaintained. You can delete these old files with prg_log_old_files_delete().
A log handle is a shorthand way of writing to a log. Using prg_log_handle_generate(), you can create a log handle with predefined values for selected columns of a log (for example, a specific category and severity). Then, when you need to make a log entry with those values for category and severity, you can use prg_log_handle_write() with that log handle. In the call, you will need to specify values only for any columns that were not predefined in the log handle. You can verify a log handle with prg_log_handle_valid() and destroy an unneeded log handle with prg_log_handle_destroy().
You can associate a log with a tfile, such as a particular scenario, with prg_log_tfile_assoc(). To export the contents of a log to a text file, use prg_log_text_export(). When you are finished with a log, you can either close it for later use with prg_log_close() or remove its files completely with prg_log_delete().