READF - Read from a formatted data file

Description:

Read input data from a formatted data file. READF attempts to read data from columns in an sequential formatted file in the most flexible manner possible. It is possible to specify the following:

• What comment delimiter characters are used within the data file - if used, the comment delimiter must be the first character of a line in the data file.

• What the column delimiters are (more than one character is possible).

• Symbolic names for each of the data columns.

The application is intended to be very robust: if a read error occurs within a line, READF will report an error and attempt to continue.

The application has many parameters for controlling how data are read, but the default values of these parameters are sufficient for reading most data files.

Usage:

readf [data] [all=?]
$\left\{ {\begin{tabular}{l} selcond=? \\ \end{tabular} } \right.$
all

Parameters:

DATA = FILENAME (Read and Write)

The name of the formatted data file.

If the value is not specified on the command line, the value of the global parameter PONGO_DATA is used. If PONGO_DATA is not defined, the current value is used. If the current value is not defined, the value is prompted for.

HARDCOM = _CHAR (Read and Write)

A character used to indicate a comment line in the data file. The character must appear in the first column of a comment.

If the value is not specified on the command line, the current value is used. The current value is initially set to "!".

SOFTCOM = _CHAR (Read and Write)

A character to indicate a comment line in the data file. This parameter allows a second character to be used as a comment delimiter. The character must appear in the first column of a comment.

If the value is not specified on the command line, the current value is used. The current value is initially set to "!".

XCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the X-axis data are read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_XCOL is used. If PONGO_XCOL is not defined, the current value is used. The current value is initially set to "0".

YCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the Y-axis data are read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_YCOL is used. If PONGO_YCOL is not defined, the current value is used. The current value is initially set to "0".

ZCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the Z-axis data are read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_ZCOL is used. If PONGO_ZCOL is not defined, the current value is used. The current value is initially set to "0".

EXCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the X-axis error data are read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_EXCOL is used. If PONGO_EXCOL is not defined, the current value is used. The current value is initially set to "0".

EYCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the Y-axis error data are read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_EYCOL is used. If PONGO_EYCOL is not defined, the current value is used. The current value is initially set to "0".

LABCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the symbolic name for each data point is read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_LABCOL is used. If PONGO_LABCOL is not defined, the current value is used. The current value is initially set to "0".

SYMCOL = _CHAR (Read and Write)

The column number (counting from 1), or the symbolic name of a column, from which the PGPLOT symbol code for each data point is read. The value "0" means "do not read these data".

If the value is not specified on the command line, the value of the global parameter PONGO_SYMCOL is used. If PONGO_SYMCOL is not defined, the current value is used. The current value is initially set to "0".

DELIM = _CHAR (Read and Write)

The character string interpreted as a column delimiter when reading the data file. For example, this can be used to read LATEX format tables by setting DELIM="&".

If the value is not specified on the command line, the current value is used. The current value is initially set to " ".

FROM = _INTEGER (Read and Write)

The first line of data to be read from the data file. The value 0 defaults to the beginning of the file. [0]

TO = _INTEGER (Read and Write)

The last line of data to be read from the data file. The value 0 defaults to the end of the file. [0]

SELCOND = _CHAR (Read and Write)

A condition (or criterion) upon which to select values from the data file. This condition has the form

[SELECT_COL] [COND] [VAL1{,VAL2, ...}]

where

• SELECT_COL is the data area used for the selection test. This can be specified either by column number (counting from 1) or by the symbolic name of a column. There is no restriction on which column is used for selection, i.e. it does not have to be one of the columns from which data are being read.

• COND is the selection criterion. It may be one of the following:
  • "=" - equals;
  • "#" - not equal;
  • "$>$" - greater than;
  • "$<$" - less than;
  • "CE" - equal to string;
  • "C#" - not equal to string;
  • "RA" - in the range VAL1 to VAL2;
  • "LI" - select if in the following list of values;
  • "EX" - exclude if in the following list of values;
  • "IN" - select if the substring is contained within the value;
  • "A$>$" - absolute value greater than;
  • "A$<$" - absolute value less than.
  
  

• VAL1{,VAL2, ...} the value (or values) against which the selection is made.

Note that there must be white space around the selection criterion. A value of "0" means "read everything".

[The value is prompted for.]

XOPT = _CHAR (Read and Write)

A string that controls the style of the X-axis labelling and tick marks. It consists of a series of letters, which are described fully in the documentation for the BOXFRAME application.

READF updates the value of the global parameters PONGO_XOPT. The application will automatically remove any "L" characters at the start of the options string, because it is assumed that they have been inserted by the CLOG application - any new data will not have had logarithms taken. If data are given in logarithmic form, the "L" character should be inserted into the options strings anywhere except at the start.

[The value of the global parameter PONGO_XOPT is used. If PONGO_XOPT is not defined, the default value "BCNST" is used.]

YOPT = _CHAR (Read and Write)

A string that controls the style of the Y-axis labelling and tick marks. It consists of a series of letters, which are described fully in the documentation for the BOXFRAME application.

READF updates the value of the global parameters PONGO_YOPT. The application will automatically remove any "L" characters at the start of the options string, because it is assumed that they have been inserted by the CLOG application - any new data will not have had logarithms taken. If data are given in logarithmic form, the "L" character should be inserted into the options strings anywhere except at the start.

[The value of the global parameter PONGO_YOPT is used. If PONGO_XOPT is not defined, the default value "BCNST" is used.]

ERSCALE = _REAL (Read)

The scale factor to be applied to the EXCOL and EYCOL data.

[The value of the global parameter PONGO_ERSCALE is used. If PONGO_ERSCALE is not defined, the default value 1.0 is used.]

ADD = _LOGICAL (Read)

If FALSE, the data values already held will be cleared before reading new data; if TRUE, the data read will be appended to the existing data. [FALSE]

ALL = _LOGICAL (Read and Write)

If TRUE, the whole data file will be read; if FALSE, a selection condition will be prompted for.

If the value is not specified on the command line, the current value is used. The current value is initially set to TRUE.

QUICK = _LOGICAL (Read and Write)

If TRUE, a "quick mode" read is performed. This mode can only be used on files which exclusively contain numeric data. This parameter can over-ride the action of the LABCOL and SELCOND parameters.

If the value is not specified on the command line, the current value is used. The current value is initially set to FALSE.

NDATA = _INTEGER (Write)

The number of data read from the data file. [0]