1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<HTML>
<HEAD>
<TITLE>READ/VECTORS command</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<P><font size="+3" color="green"><B>READ/VECTORS Command</B></font></P>
<TABLE border="1" cols="2" frame="box" rules="all" width="572">
<TR>
<TD width="15%" valign="top"><B>Syntax</B>:</TD>
<TD width="85%" valign="top"><CODE>
READ\VECTORS file{\lineRange} x1{/c1} { x2{/c2} ... }<br />
READ\FAST file{\lineRange} x1 { x2 ... }</CODE></TD>
</TR><TR>
<TD valign="top"><B>Qualifiers:</B></TD>
<TD valign="top"><CODE>
\APPEND, \ERRSTOP, \ERRSKIP, \ERRFILL, \OVERLAY, \EXTEND, \FAST</CODE></TD>
</TR><TR>
<TD valign="top"><B>Defaults:</B></TD>
<TD valign="top"><CODE>
\-APPEND, \ERRSTOP, \-OVERLAY, \EXTEND, \-FAST, cI = I</CODE></TD>
</TR>
</TABLE>
<P>
The <CODE>\FAST</CODE> 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.</P>
<P>
By default, vectors are read from columns of numbers in an ASCII file. The
file is read by records, and the <CODE>cI<SUP>th</SUP></CODE> column is placed
into vector <CODE>xI</CODE>, where <CODE>cI</CODE> defaults to <CODE>I</CODE>. Every
record is read, from the first record to the end of file. If
<CODE>xI</CODE> exists, it will be destroyed and a new <CODE>xI</CODE> vector created.
Every record is checked for errors, and if an error occurs, reading stops.</P>
<P>
A scalar appended to the file name, <CODE>file\n</CODE>, specifies the starting record.
The first <CODE>n-1</CODE> records will be skipped. A vector appended to the file name,
<CODE>file\x</CODE>, specifies each record to read. The first <CODE>x[1]-1</CODE> records will be
skipped. The data will be read from records
<CODE>x[1]</CODE>, <CODE>x[2]</CODE>, ..., <CODE>x[#]</CODE>. Records <CODE>x[1]+1</CODE> to
<CODE>x[2]-1</CODE> will be skipped. The vector <CODE>x</CODE> must be monotonically increasing.</P>
<P>
By default, the <CODE>I<SUP>th</SUP></CODE> column is placed into vector
<CODE>xI</CODE>. The column number can be specified
by appending a scalar, <CODE>cI</CODE>, to the
vector name as a qualifier. In this case, the
<CODE>cI<SUP>th</SUP></CODE> column
can be placed into the <CODE>xI</CODE> vector. For example, after:</p>
<P>
<CODE><font color="blue">READ DUM.DAT W/2 X/4 Y Z/1</font></CODE></P>
<P>
<CODE>W</CODE> would contain column <code>2</code>,
<CODE>X</CODE> would contain column <CODE>4</CODE>,
<CODE>Y</CODE> would default to column <CODE>3</CODE>, and
<CODE>Z</CODE> would contain column <CODE>1</CODE>.</P>
<P>
The <CODE>\FORMAT</CODE> 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.</P>
<P>
Standard C floating formats are valid. All values are converted to floating
point doubles for internal storage.</P>
<P>
To read only a certain number of elements into vectors use the
<CODE>\-EXTEND</CODE>, 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
<CODE>X</CODE> has length <CODE>10</CODE> and
vector <CODE>Y</CODE> has length <CODE>20</CODE>.
If you enter: <CODE><font color="blue">READ\-EXTEND file/[1:20] X Y</font></CODE> and
<CODE>20</CODE> records are read, vector
<CODE>X</CODE> will be made with a length of
<CODE>10</CODE> and vector <CODE>Y</CODE> will be
made with a length of <CODE>20</CODE>. If only <CODE>15</CODE> records are
read, vector <CODE>X</CODE> will have length
<CODE>10</CODE> but vector <CODE>Y</CODE> will
only have length <CODE>15</CODE>.</P>
<P>
By default, a new vector is created to hold the newly read data. If the
<CODE>\OVERLAY</CODE> 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
<CODE>\APPEND</CODE> qualifier to append the
newly read data onto the end of existing vectors.</P>
<P>
<CODE>\-EXTEND</CODE> is incompatible with <CODE>\OVERLAY</CODE>.<br />
<CODE>\-EXTEND</CODE> is incompatible with <CODE>\APPEND</CODE>.</P>
<P>
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,
<CODE><font color="blue">READ FILE.DAT 3X 2Y Z</font></CODE> will read
<CODE>6</CODE> numbers from each record, placing the first <CODE>3</CODE>
numbers into <CODE>X[i]</CODE>, <CODE>X[i+1]</CODE>, <CODE>X[i+2]</CODE>, the next <CODE>2</CODE>
numbers into <CODE>Y[i]</CODE>, <CODE>Y[i+1]</CODE>, and the last number into
<CODE>Z[i]</CODE>. This command is equivalent to <CODE>READ FILE.DAT X X X Y Y Z</CODE>.</P>
<P>
Records beginning with ! are considered to be comments and are ignored. </P>
<P>
By default, an invalid field stops the read, but the data that has been
read up to the error is saved. If the <CODE>\ERRSKIP</CODE> qualifier is
used, an invalid field causes the entire record to be skipped. If the
<CODE>\ERRFILL</CODE> qualifier is used, an invalid field causes the entire record to be
filled with the value of <CODE>ERRORFILL</CODE> if a format was entered, or
only the invalid field will be set to <CODE>ERRFILL</CODE> if no format
was entered. By default, <CODE>ERRORFILL=0</CODE>,
but it's value can be controlled with the <CODE>
<a href="../../Characteristics/FileRelated/errorfill.htm">ERRORFILL</a></CODE> characteristic.</P>
<P>
<a href="../readcommand.htm"><img src="../../shadow_left.gif">
<font size="+1" color="olive">READ command</font></a><br />
<a href="rvexample1.htm"><img src="../../shadow_right.gif">
<font size="+1" color="olive">Example 1</font></a></P>
</BODY>
</HTML>
|
