directive − RWP*Load Simulator directives
$directive:value
Directives are read while scanning the input files to rwloadsim and most are used to modify the behavior during parsing and code generation. They are expressly not executed and are as such not provided to the rwloadsim language parser.
All directives are initiated by $ and a sequence of lower case letters, and most then have : and another sequence of non-white-space characters that are the directive value. For number values, there is no leading sign and only positive values are accepted.
This page documents all ordinary directives.
Some directives differ slightly in syntax and are documented in these separate pages: For conditional compilation using $if $then $else $endif see conditional(1rwl). For include file processing using $include see include(1rwl). For option handling see useroption(1rwl).
$iformat:%<format>
This directive sets the printf format used whenever an integer is converted to a string; the default value is "%ld". Only formats that actually can be used to convert integers are accepted, and a warning will be displayed if the conversion isn’t valid for a (small) set of verification values.
Some useful values may be: $iformat:%08ld which makes the string representation of integers have up to 8 leading zeros. The directive $iformat:%20ld will cause the string representation of integers to have 20 characters.
The size of the internal buffer used to store the string representation of an integer is at least 30 characters, and rwloadsim ensures the buffer is not written beyond its size.
Note that in the following code snippet:
integer x := 123; $iformat:%08ld printline x;
the output will be ’123’ and not ’00000123’. The reason is that the string representation of the integer x is generated when the value 123 is assigned to it, which is before the $iformat directive. If you want the directive to be effective in this case, you need to include it before the assignment:
$iformat:%08d integer x := 123; printline x;
If you need more advanced output formatting, you should consider using the printf, fprintf or sprintf statement.
$dformat:%<format>
This is similar to $iformat, except it is used when the string representation of double variables is needed; similar restrictions apply. The default dformat is %.2f, and the same minimum 30 characters buffers is used. As an example use $dformat:%.6f to cause string representation of doubles to have 6 digits after the decimal point. As with $iformat, advanced output formatting is available using printf, fprintf or sprintf.
$randseed:<hexdigits>
The random number generator is normally provided a seed from /dev/urandom, such that different executions of rwloadsim generates different random values. If you want repeatable results, you can use this directive; the argument is any sequence of hexadecimal digits (0-9, a-f, A-F); up to twelve of these are used as the unsigned short entries in the xsubi[] array used by erand48(3) and nrand48(3). The random numbers in threads will also be repeatable as they are generated by a thread-specific permutation of bits in the xsubi[] array. You can optionally put 0x or 0X in front of the up to twelve hexadecimal digits.
$startseconds:<double>
$clockstart:<double>
These directive serves the same purpose as the -c option and they set the common start time as a number of seconds after starting rwloadsim. The directive must be used before the results database is declared. The two directives have identical behavior; the reason for having both is that the rwloadsim developer was using both of the two terms in various circumstances.
$implicit:define
$implicit:bind
$implicit:both
$implicit:off
$implicit:keepcase
$implicit:lowercase
These directives control implicit bind and define, i.e. for rwloadsim to implicitly match placeholders (bind variables) and select list elements to declared variables of the same name in your rwl program.
If any of the first three is in effect when a SQL statement is declared, that SQL statement will be subject to implicit define, bind or both, which will take place during the first execute. The fourth directive turns off both settings.
Note that you can achieve the same effect for some specific SQL statement by using either of define sql or bind sql as part of the declaration of the SQL statement. There is no semantic difference between the two, using the directive method is likely to be more appropriate if you want this for all of your SQL declarations.
By default, rwloadsim converts all letters in the bind variable name or select list element name to lowercase before matching to a declared variable. If you do not want that to happen, which implies you need your rwloadsim variable names to be in uppercase unless you use quotes in your SQL statement, use the $implicit:keepcase directive. The default behavior can be set using $implicit:lowercase.
$bindoutname:on
$bindoutname:on:identifierprefix
$bindoutname:off
These directives control how implicit bind can be used to also implicitly perform a bindout.
Normally, whenever implicit bind is in effect, either through embedded sql or through an $implicit directive, all binds are considered input binds, and values from the rwl program are provided as input to the SQL or PL/SQL text. To use a bindout where values from SQL (such as the returning clause) or PL/SQL are being output to your rwl program, you normally need an explicit bindout.
If you use either of the first two $bindoutname directives, a bindout will automatically be used whenever the name of the bind variable (placeholder) in your SQL or PL/SQL text has a specific prefix. With the first directive, the prefix is the three letters ’out’, with the second directive, the prefix is the identifier prefix found after the second ’:’. In that case, the identifier prefix must consist of an initial letter, followed by letters, numerals or underscore.
As an example, if you have been using $bindoutname:on a sql statement like
insert into mytab(pk,val) values (myseq.nextval,:val) returning pk as :outseq;
will use :outseq as a bindout which will be used with a variable named outseq.
Lowercase conversion is controlled via the $lowercase directive as explained above.
$debugon:<debuglist>
$debugoff:<debuglist>
The debugon directive has the same effect as using the -D option to the rwloadsim executable; debugoff reverses it. 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 at the rwloadsim(1rwl) page.
$mute:<integer>
$alwaysmute:<integer>
These directives will mute the rwl error with the number provided. The second directive is useful in the first file and is recognized while scanning for things like user options, which implies it will take effect very early during program start. The first directive can be controlled via $if $then directives; the second cannot.
$oraerror:stop
$oraerror:continue
The first of these tells rwloadsim to stop as soon as SQL execution gives any ORA- error. Note that doing so can imply more errors during the actual program termination. The second tells rwloadsim to continue when ORA- errors are found during SQL execution. This is the default.
$oraerror:count
$oraerror:nocount
In previous versions of rwloadsim, statistics gathering would erroneously increase the count of executions of some procedure in the RUNRES, HISTOGRAM, and PERSEC tables, even if the execution had an ORA- error. This issue is now corrected, and the counts will therefore only be increased if the execution had no ORA- error. If you want to keep the previous behavior, you can use the first of these directives. You can reset the new behavior using the second directive.
$ora01013:continue
$ora01013:stop
Normally, ctrl-c leads to a controlled stop of the executing rwloadsim process although the exact details of how clean-up is done cannot by guaranteed. If you want rwloadsim to continue after receiving an ORA-01013, use the first directive. The second, which is the default, undoes this.
$bindoffset:0
Change bind by position offset to start at zero; this is primarily useful if you are running with event 10046 tracing where bind value dumping starts at #0. With this directive set, the bind position actually used with the OCIBindByPos call is one larger than the position set at bind or bindout. The effect of the directive can be reversed by using $bindoffset:1 which is the default. Note that this directive has no impact on the numbering of select list elements used with define.
$maxcode:<integer>
$maxident:<integer>
$readbuffer:<integer>
These set the maximum size of the generated p-code, the maximum number of identifiers, or the size of the buffer used to read lines of text using readline respectively. They serve the same purpose as the -I, -C and -B options and can be used in start-up files or using the $longoption directive in the first file named with a .rwl suffix.
$statistics:basic
$statistics:histograms
$statistics:all
These have the same purpose as the -s, -ss, and -sss options respectively. They need to be used before the repository database is declared.
$statsapptime:on
$statsdbtime:on
When statistics are saved, these directives will cause values for the atime and dtime columns in the appropriate tables of the repository to also be gathered and saved. See runres(1rwl) for details. If needed, you can turn off the effect of these directives using $statsapptime:off or statsdbtime:off
$setaction:on
$setaction:reset
$setaction:off
The $setaction directives control setting the action (in v$session.action). When on, the action is set to the procedure name when a database session is acquired from a pool or a dedicated connection is being used; the action name is set using the OCI_ATTR_ACTION attribute of the session and is therefore sent to the database during the first coming actual round trip. When reset is specified, the action name is reset when the session is released or a dedicated connection no longer is in use; using reset implies an extra otherwise unnecessary round trip to the database.
You can get the same behavior using the -S or -SS option to rwloadsim.
$oerstatistics:on
$oerstatistics:off
$oerstatistics:<integer>
These directives controls saving of ORA- error statistics similar to the --oer-statistics option. They can be used to turn saving of error statistics on and off or to set the maximum number of errors saved (per thread); the default is 50.
$queue:on
$queue:off
These have the same effect as the -Q and -N options; the default is that queuing simulation using a backlog is off.
$errortime:on
$errortime:off
The first of these has the same effect as the -W option, i.e. to augment all execution time errors with a time-stamp measured as the number of seconds since clock start. It is primarily used as a debugging tool if the exact time of errors is needed. The second directive turns this off.
$nameexpand:off
$nameexpand:on
The former of these has the same effect as the --no-nameexpand option; the latter turns file name expansion using environment variable on.
$eventnotify:on
$eventnotify:off
The former has the same effect as the --event-notify option; the latter undoes --event-notify if found on the command line. These are only available in the start-up file or via $longoption directive in the first file named with a .rwl suffix.
$dbfailures:<integer>
If there is a temporary failure during declaration of a database, rwloadsim will normally consider the database to be unavailable and not continue processing. By using this directive, which must be found before your database declaration, a temporary failure will cause a re-attempt at creating the database connection. The integer value of the directive is limit to the number of connect attempts.
Using this directive will cause session pool databases to have a minimum size of at least one.
The list of errors that are considered temporary is found in rwlerror.c.
$embeddedqueryarray:<integer>
$embeddeddmlarray:<integer>
Set a default array size for respectively queries and dml when using embedded sql. Without these being set, queries in cursor loops will use OCI pre fetch using memory (currently 100k), and dml will not use array.
$ampersand:on
$ampersand:off
These directives turn ampersand replacement on and off. When on, directly embedded sql can be made dynamic by including references to declared string variables using the syntax &name.. See sqlexecution(1rwl) for details.
$sessionpool_no_rlb:on
$sessionpool_no_rlb:off
These directives control the mode used to call OCISessionPoolCreate for databases declared using sessionpool. Be default, the flag OCI_SPC_NO_RLB is set, to not set this flag, use the second directive before the database using a session pool is declared.
$pre31fileassign:on
$pre31fileassign:warn
$pre31fileassign:off
These directives control how file assignment using the := operator behave. When the directive is set to on, you can use re-direction characters such as "<", ">>", "|" as part of the name of the file causing the file to be opened for read, append or as a pipeline. When set to warn, you will get a runtime warning about such use, and if set to off, no special character interpretation will take place. In the current release (3.0.6), the default is warn; it will be set to off in release 3.1.
It is recommended that you run your rwloadsim code with warn, e.g. by putting it in your .rwloadsim.rwl file and use the generated warnings to modify your code to use the newer file assignment operators.
$niceabort:on
$niceabort:off
When the niceabort directive is turned on, executing an abort statement will produce a short warning rather than a comprehensive error. The actual effect of the abort does not change.
$queueeverytiming:on
$queueeverytiming:off
By default, whenever you have a control loop that include the queue every option, the time that is registered for waiting for a session and saved in the wtime column of the runres and persec tables, is the time actually spent in the OCISessionGet() call. However, as the queue every option is emulating an actual queue, the wait time does not include the time for the thread to wait in the emulated queue. If you use the $queueeverytiming:on directive, this time is included in the waiting time. The waiting time therefore more correctly represent the waiting time that an emulated end user would have seen. This is also the case if your database is dedicated where some execution inside a control loop starts after the calculated time.
$musymbol:<text>
When using the m or M conversion specifier in a printf statement, the µ symbol is by default output as its UTF-8 representation. This directive can be used to set any other text string, including potentially other characters outside the ASCII character set. There is no escape processing, so you must be able to enter the appropriate value using and editor.
$hostname:<text>
Set a value for the hostname rather than getting it from the Operating System; only letters a-z or A-Z, numerals, hyphen, period and underscore are allowed, and the initial character cannot be hyphen or dot. The hostname is exposed in the variable of the same name and is being inserted into the rwlrun table when statistics are gathered.
The directive is only available in a start-up file such as ~/.rwloadsim.rwl.
$sqllogging:stdout
$sqllogging:stderr
$sqllogging:file:"<text>"
$sqllogging:append:"<text>"
$sqllogging:off
These directives control logging of all sql being executed, which in particular can be useful if you rewrite sqlplus scripts to rwl scripts. The first two will turn on sql logging to either of stdout or stderr. The next two will turn on sql logging to the the file named between the double quotes; the filename can itself not contain double quote. The two directives open the file for respectively write (i.e. truncate) or for append. Expansion of environment variables will take place unless the $nameexpand:off directive is in effect. The last directives turns off sql logging.
Note that if you are running a real simulation, output can be extensive, and output from multiple threads will be intermixed.
$errordetail:on
This directive has effect if the client version is 23 or later and it turns on the full error detail which includes a url to help documentation. In earlier client versions, the directive is silently ignored.
The directive is only available in a start-up file such as ~/.rwloadsim.rwl.
$useroption:name
$userswitch:name
$longoption:option[=value]
Refer to useroption(1rwl).
$trigonometry:radians
$trigonometry:degrees
By default, the trigonometry functions, sin, cos, and atan2 use degrees. You can change this to radians using the former of these two directives.
$filelinename:<integer>:"<text>"
This directive sets the line number and the file name that will be used for error reporting. The integer provided between the first and second : set the current line number and the text between the " delimiters sets the file name. In the typical case, where the following line should be taken as the first line of some file, put the value 0 as the line number.
$include
Refer to include(1rwl).
Copyright © 2023 Oracle Corporation
Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
rwloadsim(1rwl), useroption(1rwl), longoption(1rwl), include(1rwl), conditional(1rwl), sqldeclaration(1rwl), printfstatement(1rwl), filestatement(1rwl), sqlexecution(1rwl), runres(1rwl)