-
Notifications
You must be signed in to change notification settings - Fork 18
/
filestatement.html
332 lines (255 loc) · 11.5 KB
/
filestatement.html
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Mon Mar 18 09:08:57 2024 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>filestatement</title>
</head>
<body>
<h1 align="center">filestatement</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNTAX">SYNTAX</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#USAGE">USAGE</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#EXAMPLES">EXAMPLES</a><br>
<a href="#COPYRIGHT">COPYRIGHT</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">file,
filestatement − RWP*Load Simulator use of files</p>
<h2>SYNTAX
<a name="SYNTAX"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">identifier (
<b>>=</b> | <b>>>=</b> | <b><=</b> |
<b>>|=</b> | <b><|=</b> ) concatenation</p>
<p style="margin-left:11%; margin-top: 1em">identifier
<b>:= null</b></p>
<pre style="margin-left:11%; margin-top: 1em">filestatement ::=
<b> write</b> identifier<b> ,</b> concatenation {<b> ,</b> concatenation }
|<b> writeline</b> identifier {<b> ,</b> concatenation }
|<b> readline</b> identifier<b> ,</b> identifier {<b> ,</b> identifier }
|<b> fflush</b> identifier
|<b> print</b> concatenation {<b> ,</b> concatenation }
|<b> printline</b> concatenation {<b> ,</b> concatenation }
|<b> printline
</b>readloop ::=
<b> for readline</b> identifier<b> ,</b> identifier {<b> ,</b> identifier } [<b> and</b> expression ]
<b> loop
</b> statementlist
<b> end</b> [<b> loop</b> ]</pre>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">File in
rwloadsim is implemented using FILE * from the standard I/O
library in C. A file is declared like other simple types and
can be declared publicly, privately or locally, but
<i>cannot</i> be used as an argument to procedures or
functions. Files are treated line-oriented although they are
fully buffered by the standard I/O library. Files can be
opened for reading and writing similar to how the fopen(3)
call does it and can be used as pipe-lines similar to how
popen(3) does it.</p>
<p style="margin-left:11%; margin-top: 1em">To open a file,
assign an expression containing a string to the variable,
and to close a file, assign <b>null</b> to it.</p>
<h2>USAGE
<a name="USAGE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">To open a file,
use one of the assignment syntaxes where the variable v must
be a file, and the concatenation is taken as the name of the
file or a pipeline to be executed.</p>
<p style="margin-left:11%; margin-top: 1em">v <b>>=</b>
e</p>
<p style="margin-left:17%;">Open a file for writing.</p>
<p style="margin-left:11%; margin-top: 1em">v
<b>>>=</b> e</p>
<p style="margin-left:17%;">Open the file for appending,
i.e. write at the end of the file.</p>
<p style="margin-left:11%; margin-top: 1em">v <b><=</b>
e</p>
<p style="margin-left:17%;">Open a file for reading.</p>
<p style="margin-left:11%; margin-top: 1em">v <b>>|=</b>
e</p>
<p style="margin-left:17%;">Open a pipeline for writing;
the concatenation will be given to the popen() call with a
second argument of "w".</p>
<p style="margin-left:11%; margin-top: 1em">v <b><|=</b>
e</p>
<p style="margin-left:17%;">Open a pipeline for reading;
the concatenation will be given to the popen() call with a
second argument of "r".</p>
<p style="margin-left:11%; margin-top: 1em">v <b>:=
null</b></p>
<p style="margin-left:17%;">Close a file or pipeline.</p>
<p style="margin-left:11%; margin-top: 1em">In the cases
where an ordinary file (and not a pipe-line) is opened,
environment expansion of $NAME or ${NAME} is done similar to
how it is done in the shell, unless the
<b>--no-nameexpand</b> option or the <b>$namexpand:off</b>
directive is in effect. You can also use $n where n is a
single digit between 1 and 9 to expand the value of a
positional argument to rwloadsim. This is not done for
pipelines, although the popen call is likely to do it. The
same syntax with $ for environment expansion is also used on
Microsoft Windows.</p>
<p style="margin-left:11%; margin-top: 1em">If the
concatenation is <b>null</b> the file will be closed or the
pipe-line terminated. You can use any of the assign
operators to do so.</p>
<p style="margin-left:11%; margin-top: 1em"><b>write</b> v,
e1 [, e2, ... ]</p>
<p style="margin-left:11%; margin-top: 1em"><b>print</b> e1
[, e2, ... ]</p>
<p style="margin-left:11%; margin-top: 1em"><b>writeline</b>
v [, e1 ... ]</p>
<p style="margin-left:11%; margin-top: 1em"><b>printline</b>
[e1 ... ]</p>
<p style="margin-left:17%;">Write the concatenations e1,
e2, etc to the named file with a single space character
between each. The <b>writeline</b> statement (that does not
require any actual concatenation arguments) will
additionally write a new-line. The <b>print</b> and
<b>printline</b> perform the same although writing to
stdout.</p>
<p style="margin-left:17%; margin-top: 1em">For more
advanced output, use <a href="printfstatement.html">printfstatement(1rwl)</a>.</p>
<p style="margin-left:11%; margin-top: 1em"><b>fflush</b>
v</p>
<p style="margin-left:17%;">Flush the file identified by
the variable v; this effectively calls fflush(3).</p>
<p style="margin-left:11%; margin-top: 1em"><b>readline</b>
v,s</p>
<p style="margin-left:17%;">The identifier v must be a
file, and the identifier s must be a string. The statement
reads one line from the file up to and including the newline
character and assigns the line except the terminating
newline character to the string s.</p>
<p style="margin-left:11%; margin-top: 1em"><b>readline</b>
v<b>,</b> i1<b>,</b> i2<b>,</b> ...</p>
<p style="margin-left:17%;">The identifier v must be a file
from which a line is read. The line is split into
white-space separated tokens that are assigned to the
variable i1, i2, etc. If fewer tokens than variables are
found, the last will be assigned <b>null</b> even if they
are of type string. If there are too few variables to
receive all tokens, the last variable will have the
remaining part of the line assigned to it. In all cases, if
the variables are not of type string, the usual implicit
conversion to either integer or double will take place.</p>
<p style="margin-left:11%; margin-top: 1em"><b>for
readline</b> v<b>,</b> i1<b>,</b> i2 <b>and</b> e
<b>loop</b> s;s;s; <b>end</b></p>
<p style="margin-left:17%;">The readloop reads <i>lines</i>
from a file and writes them into variables. The first
identifier, v, must be a variable of type file that is open
for read. The semantics of the readline loop is somewhat
similar to the semantics of doing something like <b>while
read ... ; do</b> in the shell. If there is only one
variable, i1, in addition to the file variable, that
variable must be of type string and the full line read from
the file (excluding the terminating newline) will be saved
in that variable.</p>
<p style="margin-left:17%; margin-top: 1em">If there are
multiple variables, i1, i2, ... they can be of type integer,
double or string. In that case, it is assumed that each line
of the file contains white-space separated tokens. The first
of these will be saved in the first variable, i1, the second
in the second variable, i2, etc. If there are more tokens in
the line read from the file than there are variables to save
those into, the last variable will contain the remaining
part of the line. If there are fewer tokens in the line read
from the file than there are variables, the last ones will
be <b>null</b>, even if they are of type string.</p>
<p style="margin-left:17%; margin-top: 1em">If you need
more complex processing of input lines, use the first form
with only one string variable to contain the whole line,
which you subsequently process using <b>regex</b> or
<b>regexextract</b>.</p>
<p style="margin-left:17%; margin-top: 1em">When
end-of-file is reached, the loop terminates; you still need
to explicitly close the file.</p>
<p style="margin-left:17%; margin-top: 1em">The optional
<b>and</b> expression before the <b>loop</b> keyword, causes
reading to stop when the expression, e, is zero; You can
similarly use a <b>break</b> statement. In either case, you
can continue reading from the file.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">You can operate
on stdin, stdout or stderr by using the predefined variables
named <b>stdin</b>, <b>stdout</b> or <b>stderr</b>
respectively. Do not close these.</p>
<p style="margin-left:11%; margin-top: 1em">Otherwise, it
is an error not to close files or pipe-lines.</p>
<p style="margin-left:11%; margin-top: 1em">Files and
pipe-lines can very well be opened, operated upon and closed
in threads. If you open files with the same name in multiple
threads, the behavior is unspecified.</p>
<p style="margin-left:11%; margin-top: 1em">If you have
files opened for read in your main program, they will be
closed in threads. This is also the case for stdin.</p>
<p style="margin-left:11%; margin-top: 1em">If you have
files opened for write in your main program, they will
continue to be open in threads. However, there is <i>no
guarantee</i> that the writes from different threads are
going to be separated. In fact, it is typically the case
that writes from different threads will be mixed, even if
you use <b>fflush</b>. This behavior is also happening for
stdout and stderr.</p>
<p style="margin-left:11%; margin-top: 1em">The readline
statement as well as the readloop read the line from their
input into a buffer that by default is 2050 bytes long. If
the actual line is longer than 2050 bytes, it will be
truncated and an error will be printed. The buffer can be
increased using the <b>--readbuffer</b> option to
rwloadsim.</p>
<p style="margin-left:11%; margin-top: 1em">In previous
versions of rwloadsim, the <b>:=</b> assignment operator
existed and the contents of the concatenation was
interpreted to open for read, write, append or as pipelines.
The actual operation was chosen by having an initial
"<", ">>", "|" or a
final "|" in the concatenation. Without any of
these, the file would be opened for writing. There is a
security concern with this, and it is therefore desupported
in release 3.1.</p>
<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Still to
come.</p>
<h2>COPYRIGHT
<a name="COPYRIGHT"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Copyright
© 2023 Oracle Corporation <br>
Licensed under the Universal Permissive License v 1.0 as
shown at https://oss.oracle.com/licenses/upl</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><a href="variable.html">variable(1rwl)</a>,
<a href="statement.html">statement(1rwl)</a>, <a href="threadexecution.html">threadexecution(1rwl)</a>, <a href="expression.html">expression(1rwl)</a>,
<a href="readloop.html">readloop(1rwl)</a>, <a href="compoundstatement.html">compoundstatement(1rwl)</a>,
<a href="printfstatement.html">printfstatement(1rwl)</a>, <a href="regex.html">regex(1rwl)</a></p>
<hr>
</body>
</html>