Read_Text_Columns

Reads an ASCII file containing any number of separated columns, often the result of exporting a spreadsheet.

Input Port


parent	UIconnection

Parameters


Filename	UIfileSB	name of the file to read
skip lines	UIfield	number of lines to skip
has header line	UItoggle	if set, use header to get column names
column separator	UIradioBox	selects column separator
user separator	UIfield	custom column separator
columns setup from file	UItoggle	if set, column names and types are determined automatically by reading first lines of file
# columns in file	UIfield	number of columns in file
Columns_Setup	UIoptionMenu	selects a column whose parameters are to be set
read column	UItoggle	if set, read this column
column name	UIfield	name of the column
data type	UIradioBox	selects the type of a column
null value	UIfield	value for missing column entries
Read File	UIbutton	causes file to be read

Output Port


table	Data_Array

Description

The Read_Text_Columns (the Network Editor name is shortened to Rd_Txt_Columns) module reads any ASCII file that contains columns of data separated by a special character or sequence of characters. These type of files often result from exporting a spreadsheet or database into a text format. The columns in the file can be of any type: character strings, integers, or real numbers. Optionally, the file can have a header line that contains the column's names. The module stops reading when it reaches the end of the file.

Here are some simple examples of column-formatted ASCII files. The following file has three columns separated by spaces:

The next file contains the same three columns of data, but the columns are separated by (nonprinting) tab characters and the file has a header:

Column-formatted ASCII files are produced by many software packages; spreadsheets are common examples.

Rd_Txt_Columns provides a number of column parameters that you can use to specify whether and how individual columns in the file are processed. You use the Column Setup menu to specify a column whose parameters you want to set, and then use the following parameters to set processing specifics:

For details, see their descriptions in the Parameters section of this reference page.

Rd_Txt_Columns outputs an array of objects of type Data_Array. You can map the output to the Uniform_Field or Scattered_Field types using the Database Kit modules Table_to_Uniform_Field or Table_to_Scattered_Field. Once mapped to Uniform_Field or Scattered_Field, the data is suitable for visualizing in AVS/Express.

Note: This module may be useful to Database Kit application developers because it allows the use of ASCII files, rather than a database, to provide sample "query output" for testing Database Kit applications. Using an ASCII file instead of establishing a test database with tables, views, and data may therefore simplify testing.

Input

Parameters

An integer that specifies the number of lines in the file to skip. The default is_0.

A toggle that causes the module to treat the first line (after skipping the number of lines specified by the skip lines parameter) as a header that contains column names. The default is OFF.

A choice of characters to use as column separators. The allowed values are "space", "tab", ",", ";", ":", and "user". If you select "user", the value specified for the user separator parameter is treated as the column separator.

A string that specifies a character or sequence of characters to be used as column separator.

This parameter is relevant only if you have also selected "user" in the column_separator parameter.

A toggle that causes the module to look at the first lines of the file to generate column names and types. If the has header line parameter is set, the header is used to generate column names, otherwise the names are "column_0", "column_1", and so forth. The type for each column is determined by examining the line following the header, if one exists.

An integer typein that specifies the number of columns in the file. If the columns_setup_from_file parameter is set, this number is generated automatically, otherwise you must enter it.

A menu that allows you to specify a column whose parameters you want to set.

A toggle that specifies whether to read the column specified by Columns_Setup or skip it.

A string typein that specifies the name of the column specified by Columns_Setup. If the columns setup from file parameter is set, the column names are generated automatically from the header if one exists, otherwise they are assigned default names. You can overwrite this string with a name of your choice.

Radio box items that specify the type of the output data for the column specified by Columns_Setup. The allowed values are byte, short, int, float, double, and string.

A value that is to be used to represent a null value for the column specified by Columns_Setup if Read_Column_File encounters a missing entry. This parameter is used only for numeric types. For strings, the "" string is substituted for a missing entry.

Output Port

An array of objects of type Data_Array. It can be converted to the Uniform_Field or Scattered_Field types using the table_to_uniform_field and table_to_scattered_field modules.