-
Notifications
You must be signed in to change notification settings - Fork 18
/
rwloadsim.html
1051 lines (790 loc) · 34 KB
/
rwloadsim.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
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Thu Jun 13 10:25:59 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>rwloadsim</title>
</head>
<body>
<h1 align="center">rwloadsim</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#OPTIONS">OPTIONS</a><br>
<a href="#USAGE">USAGE</a><br>
<a href="#INPUT FILES">INPUT FILES</a><br>
<a href="#FIRST FILE">FIRST FILE</a><br>
<a href="#ARGUMENTS">ARGUMENTS</a><br>
<a href="#STARTUP">STARTUP</a><br>
<a href="#GENERATING A BINARY">GENERATING A BINARY</a><br>
<a href="#LIMITS">LIMITS</a><br>
<a href="#VI TAGS">VI TAGS</a><br>
<a href="#EXIT VALUE">EXIT VALUE</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#BUGS">BUGS</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">rwloadsim
− The RWP*Load Simulator</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>rwloadsim
[options] file ... [arg ...]</b></p>
<p style="margin-left:11%; margin-top: 1em">The RWP*Load
Simulator is one executable that takes options, including
user defined option, rwl input files and arguments provided
to your rwl program. There must be at least one input file;
all others are optional. It is strongly recommended (and in
certain cases required) that input files are named with a
suffix of .rwl.</p>
<p style="margin-left:11%; margin-top: 1em">Most options
can be specified in the classic getopt(3) format with a
hyphen and a single option letter potentially followed by
the option value or using the GNU extension long options
with double hyphens. Some options have values required, in
which case the value is required for both the single letter
and long option form. Due to the high number of options,
some of the single letter codes appear odd and hard to
remember.</p>
<h2>OPTIONS
<a name="OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>-h
--help</b></p>
<p style="margin-left:17%;">Print short help, including
help for user options. In a generated binary, only user
options and user help is printed.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--fullhelp</b></p>
<p style="margin-left:17%;">In a generated binary, print
help for all available ordinary options in addition to user
options and help.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-H
--userhelp</b></p>
<p style="margin-left:17%;">Print the help for user options
and user help if found.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-v
--version</b></p>
<p style="margin-left:17%;">Make the banner text include
the client version</p>
<p style="margin-left:11%; margin-top: 1em"><b>-q
--quiet</b></p>
<p style="margin-left:17%;">Be quiet, no connect messages,
and some warnings muted</p>
<p style="margin-left:11%; margin-top: 1em"><b>-s
--statistics</b></p>
<p style="margin-left:17%;">Gather and save execution
statistics, this requires a results database</p>
<p style="margin-left:11%; margin-top: 1em"><b>-ss
--histograms</b></p>
<p style="margin-left:17%;">Also gather execution time
histograms</p>
<p style="margin-left:11%; margin-top: 1em"><b>-sss
--persecond</b></p>
<p style="margin-left:17%;">Also gather per second
execution counts</p>
<p style="margin-left:11%; margin-top: 1em"><b>-r
--oer-statistics</b></p>
<p style="margin-left:17%;">Save statistics about ORA-
errors</p>
<p style="margin-left:11%; margin-top: 1em"><b>-Z
--flush-stop N</b></p>
<p style="margin-left:17%;">Flush the per second statistics
every second until N seconds have passed. You would normally
want to set N to the actual stop time of your longest
running thread.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-U
--flush-every N</b></p>
<p style="margin-left:17%;">If the previous option is in
use, flush every N seconds in stead of every 1 seconds. If
you are using many worker threads and/or processes and in
particular if the latency to the repository database is
high, it is recommended to only flush every 2 or 3
seconds.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-k --key
key</b></p>
<p style="margin-left:17%;">If saving statistics, save this
key value as well; can be used to group runs</p>
<p style="margin-left:11%; margin-top: 1em"><b>-K --comment
--komment comment-text</b></p>
<p style="margin-left:17%;">If saving statistics, save this
comment-text as well; use is fully user dependent. As the
comment-text typically will be several words, it will need
to be quoted by the shell.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-c
--clockstart --startseconds N.N</b></p>
<p style="margin-left:17%;">Sets the control loop common
start time to this many seconds (as a double) after program
start. The default value is 5s.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-P --prepare
file</b></p>
<p style="margin-left:17%;">Prepare a multi-process
execution; this writes a multi-process argument to the named
file and requires the -s option and a results database.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-R
--multirun file</b></p>
<p style="margin-left:17%;">Execute a multi-process run by
reading the contents of the file created by the prepare
execution. All simultaneously running rwloadsim processes
must use the same file.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-M
--multirun-value mparg</b></p>
<p style="margin-left:17%;">Alternative way to execute a
multi-process run, by providing the contents of the file
created by the prepare run. The contents will always be a
single string without blanks, so it can easily be used in
shell scripts using ssh.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-p --procno
N</b></p>
<p style="margin-left:17%;">The value of procno stored in
the results tables. Default is 0 for single process runs,
process id for multi process runs.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-i --integer
intspec</b></p>
<p style="margin-left:17%;">Change a default value for some
integer, intspec must be variablename:=integer. The use of
this is superseded by the <b>$useroption</b> and
<b>$userswitch</b> directives.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-d --double
dblspec</b></p>
<p style="margin-left:17%;">The same for a double
variable.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-D --debug
X</b></p>
<p style="margin-left:17%;">Set debug bits, mostly used for
program debugging. You need to read the source code to get
all information about debug bits. The argument is a debug
option (or a comma separated list without spaces); each
option either a hexadecimal value (potentially prefixed by
0x or 0X) or one of the text strings shown in the following
table: <b><br>
0x004 bison</b></p>
<p style="margin-left:29%;">Set the debug flag in the
bison(1) parser.</p>
<p style="margin-left:17%;"><b>0x010 var</b></p>
<p style="margin-left:29%;">Debug handling of variables
such as declarations.</p>
<p style="margin-left:17%;"><b>0x020 exec</b></p>
<p style="margin-left:29%;">Debug execution of generated
code; this does not include code executed directly in
main.</p>
<p style="margin-left:17%;"><b>0x040 pvinternal</b></p>
<p style="margin-left:29%;">The <b>printvar all</b> will
also print all internally generated variables.</p>
<p style="margin-left:17%;"><b>0x100 eval</b></p>
<p style="margin-left:29%;">Debug evaluation of
expressions.</p>
<p style="margin-left:17%;"><b>0x200 sql</b></p>
<p style="margin-left:29%;">Debug execution of sql and
other database operations.</p>
<p style="margin-left:17%;"><b>0x800 bind define</b></p>
<p style="margin-left:29%;">Output information about all
binds and defines before first execute of some SQL; both
debug texts have the same impact as there is no way to ask
for debug of bind or define separately. This is primarily
useful if you are using implicit binds and/or defines.</p>
<p style="margin-left:17%;">Note that some debug may cause
extensive output and that the actual <br>
debug bits may change between versions.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-a
--array-size N</b></p>
<p style="margin-left:17%;">Set the default array size for
cursor for loops (fetch loops). If not set, the default will
be memory based with a target of 100k per cursor.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-C
--codesize N</b></p>
<p style="margin-left:17%;">Set the size of the p-code
array.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-I
--namecount N</b></p>
<p style="margin-left:17%;">Set the size of the identifier
array.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-L
--localnames N</b></p>
<p style="margin-left:17%;">Set the size of the array used
for local identifiers in procedures and functions</p>
<p style="margin-left:11%; margin-top: 1em"><b>-B
--readbuffer N</b></p>
<p style="margin-left:17%;">Set the size of the buffer used
to read a line of text using the readline command. The
default is 2050 bytes including the terminating null
character.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-l
--default-database u/p@c</b></p>
<p style="margin-left:17%;">Create a default database with
the specified username, password and connect string. @ and
connect string are optional. It will be a dedicated database
unless the next options are used to set the type
differently; see <a href="databasedeclaration.html">databasedeclaration(1rwl)</a> for details about
the different connection types available.</p>
<p style="margin-left:17%; margin-top: 1em">If you omit /p,
you will be prompted for the password. Regardless if you
include the password or not, rwloadsim will erase the
command line memory to prevent other users on the same
system from seeing your credentials using e.g. the ps
command.</p>
<p style="margin-left:17%; margin-top: 1em">If only / and
possibly @c are found, external (wallet) authentication is
used; see <a href="databasedeclaration.html">databasedeclaration(1rwl)</a> for details.</p>
<p style="margin-left:17%; margin-top: 1em">If you want to
provide e.g. sysdba authentication, that must be done as the
username part and you must make sure it is provided as
<i>one</i> option to rwloadsim. This is different from how
SQL*Plus does it.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-X
--default-max-pool N</b></p>
<p style="margin-left:17%;">When a default database is
created using -l option, it will be created as a session
pool of size 1..N</p>
<p style="margin-left:11%; margin-top: 1em"><b>-Y
--default-min-pool N</b></p>
<p style="margin-left:17%;">Also set the minimum pool size
for the database created using -l.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-g
--default-threads-dedicated</b></p>
<p style="margin-left:17%;">When using the -l option, make
the default database use threads dedicated.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-G
--default-reconnect</b></p>
<p style="margin-left:17%;">When using the -l option, make
the default database use reconnect.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-w
--nowarn-deprecated</b></p>
<p style="margin-left:17%;">Do not warn about use of
deprecated features.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-e
--compile-only</b></p>
<p style="margin-left:17%;">Do not execute functions,
procedures, threads and database calls (except database
declarations). This can be used to ensure input files parse
correctly and that databases are available.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-A
--argument-count N</b></p>
<p style="margin-left:17%;">The last N arguments (after all
options) are positional and will be made available as string
variables named $1, $2, etc. and the total count will be
available as $#.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-F
--file-count N</b></p>
<p style="margin-left:17%;">The first N arguments (after
all options) are rwl input file names, the rest will be
positional arguments. This option cannot be used with
-A.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-x
--execute-code code</b></p>
<p style="margin-left:17%;">Execute "code" before
reading the first file. The code can be any statement or
declaration including the terminating <b>;</b> or it can be
a directive. If the code contains a declaration with an
initialization assignment, it can be used to overwrite an
initialization value in an input file. The code provided
must be one single shell token and must therefore be
embedded in quotes if it contains white space. If needed,
the option can be repeated.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-E
--event-notify</b></p>
<p style="margin-left:17%;">Setup event-notification. The
only actual effect of the option is to make rwloadsim print
output to stdout when events such as "service
down" is received. OCISessionPool already handles these
in OCI by default and the OCI_EVENTS flag is always
specified during initialization.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-S -SS
--set-action --set-action-reset</b></p>
<p style="margin-left:17%;">Set the action
(v$session.action) to the name of the procedure whenever
that procedure acquires a session or starts using a
dedicated connection. With -SS (or -set-action-reset) a
reset of the action is done whenever the session is no
longer in use; doing so adds an extra otherwise not
necessary round-trip to the database.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-V
--no-nameexpand</b></p>
<p style="margin-left:17%;">Normally, environment expansion
is done for all files being opened (including on command
lines, via directives or using variables of type file); when
this option is in use, such expansion does not take
place.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-u
--publicsearch</b></p>
<p style="margin-left:17%;">Search for input files at
command line or in <b>$include</b> directives using "
around the file name in the public directory in addition to
the directories mentioned in the $RWLOADSIM_PATH
environment.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-Q
--queue</b></p>
<p style="margin-left:17%;">Use the <b>queue</b> option by
default for all control loops using <b>every</b>.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-N
--no-queue</b></p>
<p style="margin-left:17%;">Use the <b>noqueue</b> option
by default for all control loops using <b>every</b>. This is
the default and is therefore a no-op.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-W
--errortime</b></p>
<p style="margin-left:17%;">Augment all execution time
errors with the value returned by the runseconds()
function.</p>
<p style="margin-left:11%; margin-top: 1em"><b>-T --vi-tags
filename</b></p>
<p style="margin-left:17%;">Create a vi tags file from all
rwl files being processed; typically do this together with
--compile-only</p>
<p style="margin-left:11%; margin-top: 1em"><b>-t
--banner-local</b></p>
<p style="margin-left:17%;">When rwloadsim shows its
banner, the time included is by default in UTC as rwloadsim
generally uses UTC. To get the banner time in your local
timezone, use this option. This option does not have an
impact on the timezone used when the common start time is
saved in the rwlrun table.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--sqllogging-stdout
--sqllogging-stderr <br>
--sqllogging-file</b> filename <b>--sqllogging-append</b>
filename</p>
<p style="margin-left:17%;">These four option control
logging of sql in the same way the similar directives do.
The first two enable sql logging to respectively stdout or
stderr, the last two enable sql logging to a file that is
either opened for truncate or append.</p>
<p style="margin-left:17%; margin-top: 1em">The options are
primarily useful when using rwloadsim as a scripting tool;
when used with simulation, extensive output may be produced.
Output from multiple threads will be intermixed.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--generate
filename</b></p>
<p style="margin-left:17%;">Generate a single binary that
will execute the rwl files provided on the command line.
Such a single binary can be copied stand alone to any system
that just has an Oracle client install, and does therefore
not require a full installation of rwloadsim to execute.</p>
<p style="margin-left:17%; margin-top: 1em">This option
also sets the --compile-only option and several options and
features are unavailable when generating a binary.</p>
<p style="margin-left:17%; margin-top: 1em">The following
options can be used to change the binary.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--generate-name
name</b></p>
<p style="margin-left:17%;">By default, the (internal) name
of the generated binary will be the same as the last path of
the filename; this option sets an explicit name. The
internal name is used in several contexts such as the banner
and for error reporting.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--generate-banner
’Banner text’</b></p>
<p style="margin-left:17%;">The default banner of the
generated binary is ’RWP*Load Simulator (name)’;
use this option to set a different banner.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--generate-command
command</b></p>
<p style="margin-left:17%;">When generating a binary, the C
compiler is invoked, which by default is done using
’generate.sh’ in the lib directory. You can
provide a different command, which typically should be an
executable shell script. The text provided to the option
should have four %s followed by a single %d, and is given
the following five parameters via sprintf. Note that the
first and the second %s will be given the same value.</p>
<p style="margin-left:23%;">1. Full pathname of the lib
directory, by default used to identify the directory where
the command is stored. <br>
2. Full pathname of the lib directory, by default used as an
argument to the command itself. <br>
3. The typically relative pathname to the generated
executable. <br>
4. The full pathname of the C source code to be compiled.
<br>
5. The major compile version of Oracle Call Interface, such
as 19 or 21.</p>
<p style="margin-left:17%;">If the option is not provided,
the text string "%s/generate.sh %s %s %s %d" is
used. This and the existing generate.sh can be used as a
template for any modifications required.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--generate-directory
directory</b></p>
<p style="margin-left:17%;">When generating a binary, an
intermediate C source code is created in a temporary
directory, which is subsequently deleted. Use this option to
specify an existing directory in stead; this implies the
intermediate C source code is kept after generating the
binary.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--list-generated</b></p>
<p style="margin-left:17%;">Write the complete generated
code to stdout and then exit; this option is only available
in a generated executable.</p>
<h2>USAGE
<a name="USAGE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">After
processing all options, the files given as arguments will be
opened and processed in sequence. If you put the traditional
-- marker between the options and the list of files, you can
replace a file argument by a single argument containing
’-x code’ causing the same behavior as a -x
option. As an example, the following:</p>
<p style="margin-left:11%; margin-top: 1em"><b>rwloadsim -q
-- ’-x printline "hello,
world";’</b></p>
<p style="margin-left:11%; margin-top: 1em">will do nothing
but printing the text hello, world. Note that the complete
text, including both -x and the code to be executed must be
contained within one single shell argument to rwloadsim.</p>
<h2>INPUT FILES
<a name="INPUT FILES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Whenever
rwloadsim opens a file, it will attempt doing expansion of
environment variable names using either $NAME or ${NAME}
syntax as in the shell. This is the case both for files
named on the command line, and for files named using the
<b>$include</b> directive and several other occasions. The
same syntax with $ for environment expansion is also used on
Microsoft Windows.</p>
<p style="margin-left:11%; margin-top: 1em">Each such file
provided to rwloadsim (including implicitly using -x) must
be "complete", and you can e.g. not have a
procedure header in one file and the body in a second one.
So each file must contain a complete rwloadsim program
element including the terminating <b>;</b>. Files mentioned
on the command line or in <b>$include</b> directives using
" around the file name will be attempted opened at the
current directory. If the file does not exist and the file
name does not begin with / or ., the contents of the
RWLOADSIM_PATH environment, which should be a : separated
list of directories will be searched. Further, if the
<b>-u</b> or <b>--publicsearch</b> option is provided, the
public directory will be searched before RWLOADSIM_PATH
directories are searched. The public directory is relative
to the bin directory where the rwloadsim executable is
found. File names that start with / or . will never be
searched for.</p>
<h2>FIRST FILE
<a name="FIRST FILE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The first
argument named on the command line that appears like a file
name with a .rwl suffix is opened and scanned before any
other option or argument scanning is taking place. This
initial scan of the first file is done <i>only</i> to look
for <b>$longoption</b>, <b>$useroption</b> or
<b>$userswitch</b> directives.</p>
<p style="margin-left:11%; margin-top: 1em">Further details
are available in <a href="useroption.html">useroption(1rwl)</a>. The file is therefore
scanned once more with normal processing after handling
options. Only the first file has this special early
scan.</p>
<h2>ARGUMENTS
<a name="ARGUMENTS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">By default, all
non option arguments are used as input files. If your
programming requires positional arguments, these can
provided similar to how it is done in shell by using either
the <b>-A</b> or the <b>-F</b> option or by separating file
arguments from positional arguments by <b>;</b> (which must
be escaped by the shell) or <b>--</b>.</p>
<p style="margin-left:11%; margin-top: 1em">The -A option
value is the count of positional arguments and it implies
that many arguments at the end of the rwloadsim command line
are positional rather than rwl input files to be read.
Alternatively, the -F option specifies how many arguments
(after all options) are taken as rwl input files; the rest
will be positional. The third possibility where you
don’t need to specify the count of either files or
arguments, is to separate the list of files from the list of
arguments by a single <b>;</b> (which must be escaped by the
shell). You can also use <b>--</b> (two hyphens) in stead of
the single <b>;</b>, but you then need to have two
occurrences of of <b>--</b> on your command line, as
getopt(3C) uses the first of these to mean the end of
options. You can use the method that is best suited for your
scripting; they effectively serve the same purpose.</p>
<h2>STARTUP
<a name="STARTUP"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">During startup,
you can provide directives in either an environment variable
or in a startup file. Either approach is useful if you want
to generally change certain settings; as an example you can
use it for a $iformat directive.</p>
<p style="margin-left:11%; margin-top: 1em">If the the
RWLOADSIMINIT environment exist, any directives found will
be handled. No other contents such as rwl language
statements are allowed.</p>
<p style="margin-left:11%; margin-top: 1em">If the file
pointed to by the environment variable RWLOADSIMRC is
readable it will be read during startup, otherwise if
$HOME/.rwloadsim.rwl exists, it will be read. On Microsoft
Windows, the file is %HOMEDRIVE%%HOMEPATH%/.rwloadsim.rwl.
The startup file can only contain comments and
directives.</p>
<h2>GENERATING A BINARY
<a name="GENERATING A BINARY"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The RWP*Load
Simulator can be used to generate a single executable binary
file, which can be copied to any system without an rwloadsim
installation. The use of this is to make some rwl script
available for execution anywhere. In binary generate mode,
the following happens:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>1.</p></td>
<td width="3%"></td>
<td width="83%">
<p>The rwl scripts provided on the command line are read in
compile-only mode and are output to an intermediate C source
file.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>2.</p></td>
<td width="3%"></td>
<td width="83%">
<p>The C source file is compiled and linked with slightly
modified rwloadsim object files, such that the generated rwl
code is executed.</p></td></tr>
</table>
<p style="margin-left:11%; margin-top: 1em">Certain
constraints apply for this feature:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em">1.</p></td>
<td width="3%"></td>
<td width="83%">
<p style="margin-top: 1em">When generating a binary, you
cannot declare any databases in the rwl files provided. You
can, however, execute SQL against the default database, as
the generated binary can be executed using the -l
option.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>2.</p></td>
<td width="3%"></td>
<td width="83%">
<p>Any $include directives will be <i>copied</i> to the
generated executable rather than being used during
generation. Note that unless the $include directive is
excluded via $if $then, the file must be present when the
generated executable is executed.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p> </p></td>
<td width="3%"></td>
<td width="83%">
<p>This can be used if you have a file that e.g. declares a
standard procedure used in several generated files. Assuming
such a procedure is called myproc() and is declared in the
file myproc.rwl, you can have myproc.rwl on the command line
while you generate an executable and make sure it gets
included otherwise using something like the following:</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p> </p></td>
<td width="3%"></td>
<td width="83%">
<pre style="margin-top: 1em">$if !defined(myproc) $then $include:<myproc.rwl> $endif</pre>
</td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>3.</p></td>
<td width="3%"></td>
<td width="83%">
<p>The generated binary cannot interact with the repository
database and any associated options are disabled.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>4.</p></td>
<td width="3%"></td>
<td width="83%">
<p>When generating a binary, all files (named with a .rwl
suffix) are scanned for e.g. $useroption directives, and
these are therefore also used in the generated binary.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>5.</p></td>
<td width="3%"></td>
<td width="83%">
<p>During generation, all arguments are rwl input files and
no positional arguments can be provided. In the generated
binary, the opposite is the case and it will by default use
all arguments as positional. The options -F and -A options
do therefore also not have any effect in the generated
binary. If you want it to read one (or more) rwl scripts
before executing the actual generated code, you can use
either <b>;</b> or <b>--</b> methods to separate files from
positional arguments as described under ARGUMENTS above. Any
such file will be read and executed <i>before</i> the
generated code.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p> </p></td>
<td width="3%"></td>
<td width="83%">
<p>The primary use of this is if your generated code
requires a default database, and you prefer to have that
declared in an rwl file rather than using the -l command
line option. Note that this effectively gives you <i>two</i>
files that are scanned for things like $useroption
directives; both the first file provided during generation
and the possible first file provided when the generated
binary is executed.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p> </p></td>
<td width="3%"></td>
<td width="83%">
<p>An example of how to do this with a generated binary
called "mygen" and an rwl file called mydb.rwl
is</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p> </p></td>
<td width="3%"></td>
<td width="83%">
<pre style="margin-top: 1em">mygen mydb.rwl ’;’ arg1 arg2</pre>
</td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>6.</p></td>
<td width="3%"></td>
<td width="83%">
<p>Several features are unavailable in the generated
binary.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>7.</p></td>
<td width="3%"></td>
<td width="83%">
<p>The full text of your rwl program is visible in the
generated executable. You should therefore <i>not</i> put
any passwords or other sensitive information in in rwl
source files used to generate an executable. During
generation, rwloadsim will scan for certain sensitive
keywords and emit a warning if any of these are found; this
scan is however not guaranteed to be precise.</p></td></tr>
</table>
<h2>LIMITS
<a name="LIMITS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">During parsing
and execute of your rwloadsim program, some structures are
allocated as fixed size arrays. The sizes are set to such
that they are expected to be sufficiently large for any
typical rwloadsim program; they can only be increased by
modifying the rwl.h source and recompiling. The limits and
their values are:</p>
<p style="margin-left:17%; margin-top: 1em">Maximum
recursive function calls during parse; 42.</p>
<p style="margin-left:17%; margin-top: 1em">Highest number
of recursive short-circuit operations during parse; 254.</p>
<p style="margin-left:17%; margin-top: 1em">Deepest number
of file inclusion during parse; 42.</p>
<p style="margin-left:17%; margin-top: 1em">Highest depth
of any compound statement (if/then/else, loops, etc) during
parse; 42.</p>
<p style="margin-left:17%; margin-top: 1em">Deepest nesting
of $if/$then/$else/$endif directives during parse; 30.</p>
<p style="margin-left:17%; margin-top: 1em">Deepest
function/procedure recursion level during execute; 42.</p>
<h2>VI TAGS
<a name="VI TAGS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">You can create
a vi tags file with the specified name using the -T option,
which you typically should use together with the -e option.
Tags file creation is still experimental and it does e.g.
not deal with cases, where you have run commands to start
threads in multiple rwl files. The first run command found
will be used to create a tag named "run", so you
can use it with vi by typing ’vi -t run’. There
will also be a tag named runxx, which refers to the run
command in the file named xx.rwl. If you have multiple
simulations and/or multiple files with run commands in the
same directory, it may be beneficial to create different
tags files, tags1, tags2, etc and subsequently merge these
using a command line like:</p>
<p style="margin-left:11%; margin-top: 1em"><b>env LC_ALL=C
sort -u tags1 tags2 > tags</b></p>
<h2>EXIT VALUE
<a name="EXIT VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">If errors are
generated, the exit value will be non-zero; it will be a bit
pattern with the following meaning: 0x1 are severe errors
causing immediate stop, 0x2 when parse errors are found, 0x4
when minor errors allowing continuation are found, 0x8 when
any errors during runtime are seen. If your rwloadsim
program does an explicit exit, that value will be used.</p>
<h2>NOTES
<a name="NOTES"></a>