rwloadsim − The RWP*Load Simulator
rwloadsim [options] file ... [arg ...]
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.
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.
-h --help
Print short help, including help for user options. In a generated binary, only user options and user help is printed.
--fullhelp
In a generated binary, print help for all available ordinary options in addition to user options and help.
-H --userhelp
Print the help for user options and user help if found.
-v --version
Make the banner text include the client version
-q --quiet
Be quiet, no connect messages, and some warnings muted
-s --statistics
Gather and save execution statistics, this requires a results database
-ss --histograms
Also gather execution time histograms
-sss --persecond
Also gather per second execution counts
-r --oer-statistics
Save statistics about ORA- errors
-Z --flush-stop N
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.
-U --flush-every N
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.
-k --key key
If saving statistics, save this key value as well; can be used to group runs
-K --comment --komment comment-text
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.
-c --clockstart --startseconds N.N
Sets the control loop common start time to this many seconds (as a double) after program start. The default value is 5s.
-P --prepare file
Prepare a multi-process execution; this writes a multi-process argument to the named file and requires the -s option and a results database.
-R --multirun file
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.
-M --multirun-value mparg
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 --procno N
The value of procno stored in the results tables. Default is 0 for single process runs, process id for multi process runs.
-i --integer intspec
Change a default value for some integer, intspec must be variablename:=integer. The use of this is superseded by the $useroption and $userswitch directives.
-d --double dblspec
The same for a double variable.
-D --debug X
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:
0x004 bison
Set the debug flag in the bison(1) parser.
0x010 var
Debug handling of variables such as declarations.
0x020 exec
Debug execution of generated code; this does not include code executed directly in main.
0x040 pvinternal
The printvar all will also print all internally generated variables.
0x100 eval
Debug evaluation of expressions.
0x200 sql
Debug execution of sql and other database operations.
0x800 bind define
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.
Note that some debug may cause
extensive output and that the actual
debug bits may change between versions.
-a --array-size N
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.
-C --codesize N
Set the size of the p-code array.
-I --namecount N
Set the size of the identifier array.
-L --localnames N
Set the size of the array used for local identifiers in procedures and functions
-B --readbuffer N
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.
-l --default-database u/p@c
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 databasedeclaration(1rwl) for details about the different connection types available.
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.
If only / and possibly @c are found, external (wallet) authentication is used; see databasedeclaration(1rwl) for details.
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 one option to rwloadsim. This is different from how SQL*Plus does it.
-X --default-max-pool N
When a default database is created using -l option, it will be created as a session pool of size 1..N
-Y --default-min-pool N
Also set the minimum pool size for the database created using -l.
-g --default-threads-dedicated
When using the -l option, make the default database use threads dedicated.
-G --default-reconnect
When using the -l option, make the default database use reconnect.
-w --nowarn-deprecated
Do not warn about use of deprecated features.
-e --compile-only
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.
-A --argument-count N
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 $#.
-F --file-count N
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.
-x --execute-code code
Execute "code" before reading the first file. The code can be any statement or declaration including the terminating ; 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.
-E --event-notify
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.
-S -SS --set-action --set-action-reset
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.
-V --no-nameexpand
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.
-u --publicsearch
Search for input files at command line or in $include directives using " around the file name in the public directory in addition to the directories mentioned in the $RWLOADSIM_PATH environment.
-Q --queue
Use the queue option by default for all control loops using every.
-N --no-queue
Use the noqueue option by default for all control loops using every. This is the default and is therefore a no-op.
-W --errortime
Augment all execution time errors with the value of the runseconds variable.
-T --vi-tags filename
Create a vi tags file from all rwl files being processed; typically do this together with --compile-only
-t --banner-local
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.
--sqllogging-stdout
--sqllogging-stderr
--sqllogging-file filename --sqllogging-append
filename
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.
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.
--generate filename
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.
This option also sets the --compile-only option and several options and features are unavailable when generating a binary.
The following options can be used to change the binary.
--generate-name name
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.
--generate-banner ’Banner text’
The default banner of the generated binary is ’RWP*Load Simulator (name)’; use this option to set a different banner.
--generate-command command
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.
1. Full pathname of the lib
directory, by default used to identify the directory where
the command is stored.
2. Full pathname of the lib directory, by default used as an
argument to the command itself.
3. The typically relative pathname to the generated
executable.
4. The full pathname of the C source code to be compiled.
5. The major compile version of Oracle Call Interface, such
as 19 or 21.
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.
--generate-directory directory
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.
--list-generated
Write the complete generated code to stdout and then exit; this option is only available in a generated executable.
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:
rwloadsim -q -- ’-x printline "hello, world";’
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.
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 $include directive and several other occasions.
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 ;. Files mentioned on the command line or in $include 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 -u or --publicsearch 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.
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 only to look for $longoption, $useroption or $userswitch directives.
Further details are available in useroption(1rwl). The file is therefore scanned once more with normal processing after handling options. Only the first file has this special early scan.
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 -A or the -F option or by separating file arguments from positional arguments by ; (which must be escaped by the shell) or --.
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 ; (which must be escaped by the shell). You can also use -- (two hyphens) in stead of the single ;, but you then need to have two occurrences of of -- 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.
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.
If the the RWLOADSIMINIT environment exist, any directives found will be handled. No other contents such as rwl language statements are allowed.
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.
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:
|
1. |
The rwl scripts provided on the command line are read in compile-only mode and are output to an intermediate C source file. | ||
|
2. |
The C source file is compiled and linked with slightly modified rwloadsim object files, such that the generated rwl code is executed. |
Certain constraints apply for this feature:
|
1. |
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. | ||
|
2. |
Any $include directives will be copied 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. | ||
|
|
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: | ||
|
|
$if !defined(myproc) $then $include:<myproc.rwl> $endif | ||
|
3. |
The generated binary cannot interact with the repository database and any associated options are disabled. | ||
|
4. |
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. | ||
|
5. |
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 ; or -- methods to separate files from positional arguments as described under ARGUMENTS above. Any such file will be read and executed before the generated code. | ||
|
|
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 two 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. | ||
|
|
An example of how to do this with a generated binary called "mygen" and an rwl file called mydb.rwl is | ||
|
|
mygen mydb.rwl ’;’ arg1 arg2 | ||
|
6. |
Several features are unavailable in the generated binary. | ||
|
7. |
The full text of your rwl program is visible in the generated executable. You should therefore not 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. |
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:
Maximum recursive function calls during parse; 42.
Highest number of recursive short-circuit operations during parse; 254.
Deepest number of file inclusion during parse; 42.
Highest depth of any compound statement (if/then/else, loops, etc) during parse; 42.
Deepest nesting of $if/$then/$else/$endif directives during parse; 30.
Deepest function/procedure recursion level during execute; 42.
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:
env LC_ALL=C sort -u tags1 tags2 > tags
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.
There are probably bugs. One known bug is that this manual does not have a list of bugs.
It is also reasonable to consider the large amount of options a bug, but such is evolution and the problem is likely to get worse over time. There are only a few lower case characters and one upper case character that are not used as single option letters.
Copyright
© 2023 Oracle Corporation
Licensed under the Universal Permissive License v 1.0 as
shown at https://oss.oracle.com/licenses/upl
rwlman(1rwl), rwl(1rwl), directive(1rwl), statement(1rwl), useroption(1rwl), rwlrun(1rwl), statistics(1rwl), rwlerror(1rwl), databasedeclaration(1rwl)