op_prg_gdf_read()
Abstract
Reads the contents of an ASCII GDF (general data file) or CSV (comma-separated value) file, and returns the file contents as a list of strings.
Syntax
op_prg_gdf_read (file_name)
| Argument | Type | Description |
|---|---|---|
file_name |
const char* |
name of the file to read [This argument must match the name of a general data file (.gdf suffix) or a comma-separated value file (.csv suffix) contained in the model directories. There must be no path or suffix specified in the file name argument. It is usually convenient for generic process models to obtain specific file names using object attributes: the file names are assigned to attributes using environment files or the Network or Node Editors, and these names are obtained using the KP op_ima_obj_attr_get().]. |
Return Type
List*
Pointer to a list of strings representing lines read from the file. Each line of the file is copied into a string within the returned list. If the file could not be opened, the symbolic constant OPC_NIL is returned.
Example
Excerpt from: example model (std/ip); external C file (ip2_rte_sup.ex.c); function (arp_sup_table_load()).
List*
arp_sup_table_load (file_name)
{
List * line_list_ptr;
char err_str [256]
/* Read in an address-map table from an ASCII */
/* file adhering to the format defined above. */
FIN (arp_sup_table_load (file_name))
/* Open and read the file into the list. */
line_list_ptr = op_prg_gdf_read (file_name);
/* Test for error in reading. */
if (line_list_ptr == OPC_NIL)
{
sprintf (err_str, "File Name: %s", file_name);
op_sim_end ("Package : arp_sup", <...>
Details
This KP looks first for a general data file (.gdf suffix) with the specified name within a model directory. If none is found, it looks in the model directories for a comma-separated value file (.csv suffix) with the specified name. The use of a GDF is convenient because these files can be assigned to object attributes using menus within the application. For comma-separated value files, the returned list contains one entry for each line of comma-separated values in the specified file.
The requested file is opened before being read and closed after being read, thus providing an all-in-one file operation. Invoking this KP has no destructive or modifying effect on the file. The contents of the file are returned in a list of strings, with the beginning of the file starting at the head of the list and end of the file at the tail of the list. The list is created within this KP and can later be cleared out using the KP op_prg_list_free().
Several processing functions are performed on the file contents:
- Blank lines (consisting of only white space) are not placed in the list
- Comment lines that start with a pound sign (#) in the first column are not placed in the list
- Leading white space on each line is removed
Purpose
Provides a mechanism for reading in ASCII text information from files, thus avoiding direct use of the standard I/O functions (such as fopen(), fread(), and fclose()). This is typically useful for processes that need to load in tabular information stored in files, such as routing tables. In a single function call, the file is located and opened, its contents read and organized into a list, non-interesting lines are avoided, and the file is closed. The returned list can then be conveniently manipulated using the KPs op_prg_list_access() or op_prg_list_remove().
Errors
- Program Abort: Segmentation Violation. (due to invalid file_name argument)
- Program Abort: Allocation of memory failed.
- Recoverable Error: File (
<file_name>) cannot be opened for reading. - Recoverable Error: Allocation of memory failed while reading file (
<file_name>). Line list is truncated where reading stopped.
Reference
- Use the KP op_prg_list_free() to deallocate the contents of the list returned by this KP
- Use the KP op_prg_mem_free() to deallocate the list structure memory allocated by this KP
- Use the KP op_prg_list_access() to obtain a pointer to a single line in the list returned by this KP
- Use the KP op_prg_list_remove() to remove a single line (and obtain a pointer to it) from the list returned by this KP
- Use the KP op_prg_str_decomp() to decompose a line of the file into a series of field strings