READ/VECTORS Command
Syntax: |
READ\VECTORS file{\lineRange} x1{/c1} { x2{/c2} ... } |
Qualifiers: |
\APPEND, \ERRSTOP, \ERRSKIP, \ERRFILL, \OVERLAY, \EXTEND, \FAST |
Defaults: |
\-APPEND, \ERRSTOP, \-OVERLAY, \EXTEND, \-FAST, cI = I |
The \FAST
qualifier only applies to
reading vectors. All vectors being read must exist already, and will not be
extended by the read. No error checking is done. No column numbers and no
format may be used. Any error during the read will simply stop the read. A
line range may be entered as a file qualifier.
By default, vectors are read from columns of numbers in an ASCII file. The
file is read by records, and the cIth
column is placed
into vector xI
, where cI
defaults to I
. Every
record is read, from the first record to the end of file. If
xI
exists, it will be destroyed and a new xI
vector created.
Every record is checked for errors, and if an error occurs, reading stops.
A scalar appended to the file name, file\n
, specifies the starting record.
The first n-1
records will be skipped. A vector appended to the file name,
file\x
, specifies each record to read. The first x[1]-1
records will be
skipped. The data will be read from records
x[1]
, x[2]
, ..., x[#]
. Records x[1]+1
to
x[2]-1
will be skipped. The vector x
must be monotonically increasing.
By default, the Ith
column is placed into vector
xI
. The column number can be specified
by appending a scalar, cI
, to the
vector name as a qualifier. In this case, the
cIth
column
can be placed into the xI
vector. For example, after:
READ DUM.DAT W/2 X/4 Y Z/1
W
would contain column 2
,
X
would contain column 4
,
Y
would default to column 3
, and
Z
would contain column 1
.
The \FORMAT
qualifier must be used
to indicate that a format is present. The format must be enclosed in quotes.
If a format is used, column numbers cannot be specified.
Standard C floating formats are valid. All values are converted to floating point doubles for internal storage.
To read only a certain number of elements into vectors use the
\-EXTEND
, qualifier. The output
length of a vector will be number of values that are read, to a maximum of
that vector's original length. For example, suppose that vector
X
has length 10
and
vector Y
has length 20
.
If you enter: READ\-EXTEND file/[1:20] X Y
and
20
records are read, vector
X
will be made with a length of
10
and vector Y
will be
made with a length of 20
. If only 15
records are
read, vector X
will have length
10
but vector Y
will
only have length 15
.
By default, a new vector is created to hold the newly read data. If the
\OVERLAY
qualifier is used, an
existing vector will have the newly read data overlayed on the original
data. The resultant vector length may be longer, but never shorter. Use the
\APPEND
qualifier to append the
newly read data onto the end of existing vectors.
\-EXTEND
is incompatible with \OVERLAY
.
\-EXTEND
is incompatible with \APPEND
.
Field counts must be literal integers, that is, they cannot be scalar
variables. Field counts are specified by an integer preceding the vector
name. For example,
READ FILE.DAT 3X 2Y Z
will read
6
numbers from each record, placing the first 3
numbers into X[i]
, X[i+1]
, X[i+2]
, the next 2
numbers into Y[i]
, Y[i+1]
, and the last number into
Z[i]
. This command is equivalent to READ FILE.DAT X X X Y Y Z
.
Records beginning with ! are considered to be comments and are ignored.
By default, an invalid field stops the read, but the data that has been
read up to the error is saved. If the \ERRSKIP
qualifier is
used, an invalid field causes the entire record to be skipped. If the
\ERRFILL
qualifier is used, an invalid field causes the entire record to be
filled with the value of ERRORFILL
if a format was entered, or
only the invalid field will be set to ERRFILL
if no format
was entered. By default, ERRORFILL=0
,
but it's value can be controlled with the
ERRORFILL
characteristic.