op_prg_gdf_read()
摘要
读取 ASCII GDF(通用数据文件)或 CSV(逗号分隔值)文件的内容,并以字符串列表形式返回文件内容。
语法
op_prg_gdf_read (file_name)
| 参数 | 类型 | 说明 |
|---|---|---|
file_name |
const char* |
要读取的文件名 [该参数必须与模型目录中包含的某个通用数据文件(.gdf 后缀)或逗号分隔值文件(.csv 后缀)的名称匹配。文件名参数中不得指定路径或后缀。通常,通用进程模型通过对象属性获取具体文件名会比较方便:文件名通过环境文件或网络编辑器、节点编辑器赋值给属性,而这些名称通过内核过程 op_ima_obj_attr_get() 获取。]。 |
返回类型
List*
指向字符串列表的指针,列表中的每个字符串对应从文件读取的一行。文件的每一行都被复制到返回列表中的一个字符串里。如果文件无法打开,则返回符号常量 OPC_NIL。
示例
摘自:示例模型(std/ip);外部 C 文件(ip2_rte_sup.ex.c);函数(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", <...>
详情
该内核过程首先在模型目录中查找具有指定名称的通用数据文件(.gdf 后缀)。如果未找到,则在模型目录中查找具有指定名称的逗号分隔值文件(.csv 后缀)。使用 GDF 很方便,因为这些文件可以通过应用程序中的菜单赋值给对象属性。对于逗号分隔值文件,返回的列表为指定文件中的每一行逗号分隔值提供一个条目。
请求的文件在读取前打开、读取后关闭,从而提供一体化的文件操作。调用该内核对文件没有任何破坏或修改作用。文件内容以字符串列表形式返回,文件的开头对应列表的头部,文件结尾对应列表尾部。该列表在此内核过程内创建,之后可以用内核过程 op_prg_list_free() 清除。
对文件内容执行以下几项处理:
- 空行(仅由空白组成)不放入列表
- 第一列以井号(#)开头的注释行不放入列表
- 每行开头的空白会被去除
用途
提供一种从文件读取 ASCII 文本信息的机制,从而避免直接使用标准 I/O 函数(如 fopen()、fread() 和 fclose())。这对需要加载存储在文件中的表格信息(如路由表)的进程通常很有用。在一次函数调用中,文件被定位并打开、内容被读取并组织成列表、无需关注的行被跳过、文件被关闭。返回的列表随后可以方便地用内核过程 op_prg_list_access() 或 op_prg_list_remove() 进行操作。
错误
- 程序中止:段错误。(由于
file_name参数无效) - 程序中止:内存分配失败。
- 可恢复错误:文件(
<file_name>)无法打开读取。 - 可恢复错误:读取文件(
<file_name>)时内存分配失败。行列表在停止读取处被截断。
参考
- 使用内核过程 op_prg_list_free() 释放该内核过程返回的列表内容
- 使用内核过程 op_prg_mem_free() 释放该内核过程分配的列表结构内存
- 使用内核过程 op_prg_list_access() 获取该内核过程返回列表中某一行的指针
- 使用内核过程 op_prg_list_remove() 从该内核过程返回的列表中移除某一行(并获得其指针)
- 使用内核过程 op_prg_str_decomp() 将文件的一行分解为一系列字段字符串