prg_gdf_read()
Abstract
Reads the contents of an ASCII file and returns the file contents as a list of strings.
Syntax
prg_gdf_read (file_name)
| Argument | Type | Description |
|---|---|---|
file_name |
char* |
name of the file to read. If this argument is given as only a file name (no path or suffix), it must match the name of a general data file ( .gdf suffix) contained in the model directories.If this argument is given as an absolute path name, it can be any ASCII file (such as a general data file or comma-separated value file). |
Return Type
Prg_List*
Pointer to a list of strings representing lines read from the specified 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 PRGC_NIL is returned.
Header
prg_file_funcs.h
Example
Prg_List*
arp_sup_table_load (file_name)
{
Prg_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 = prg_gdf_read (file_name);
/* Test for error in reading. */
if (line_list_ptr == PRGC_NIL)
{
sprintf (err_str, "File Name: %s", file_name);
op_sim_end ("Package: arp_sup", <...>
Details
This function looks in the model directories for the specified ASCII file, either:
- A general data file (
.gdfsuffix), if only a file name is specified - Any ASCII file (
.gdf,.csv, or other suffix), if a full path name and suffix is specified
The ASCII file is opened by this function before being read and closed after being read, thus providing an all-in-one file operation. Invoking this function 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 the end of the file at the tail of the list. The list is created within this function and can later be cleared out using 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 prg_list_access() or prg_list_remove().
The function prg_tfile_generic_data_file_read() expands the functionality of prg_gdf_read() by also supporting generic settings files (.gsf) and by allowing the returned strings to be appended to a specified list.
Errors
- Program Abort: Segmentation Violation. (due to invalid file_name argument)
- Program Abort: Allocation of memory failed.
- Recoverable Error: Unable to open file (<file_name>) for reading
- Recoverable Error: Unable to allocate sufficient memory for reading from (<file_name>).
Reference
- use prg_list_free() to deallocate the contents of the list returned by this function
- use prg_mem_free() to deallocate the list structure memory allocated by this function
- use prg_list_access() to obtain a pointer to a single line in the list returned by this function
- use prg_list_remove() to remove a single line (and obtain a pointer to it) from the list returned by this function
- use prg_str_decomp() to decompose a line of the file into a series of field strings