READ/VECTORS Command

Syntax: | `READ\VECTORS file{\lineRange} x1{/c1} { x2{/c2} ... } READ\FAST file{\lineRange} x1 { x2 ... }`
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.

Example 1
Example 2
Example 3

READ command
Read scalars