5. Configuring Driver Script options

To configure the Driver Script select Options under the Driver Script tree-view.

Figure 4.16. Driver Script Options

Driver Script Options

This displays the Driver Script Options dialog. The connection options are common to the Schema Build Dialog in addition to new Driver Options. For advanced options more details are provided in the subsequent section.

Figure 4.17. Driver Script Options

Driver Script Options

Table 4.7. Driver Script Options

OptionDescription
TPROC-C Driver ScriptFor all databases you have the option of selecting a Test Driver Script or a Timed Driver Script. The This choice will dynamically change the Driver Script that is loaded when the TPROC-C Driver Script menu option is chosen. The Test Driver Script is intended for verifying and testing a configuration only by displaying virtual user output for a small number of virtual users. In particular both Windows and Linux graphical displays are single-threaded permitting only one Virtual User to write to the display at any one time. Therefore the performance of writing to the display will limit throughput. Consequently once a schema is verified to conduct measured tests you should select the Timed Driver Script Option.
Total Transactions per UserTotal transactions per user is reported as total_iterations within the EDITABLE OPTIONS section of the driver script. This value will set the number of transactions each virtual user will process before logging off. You can use this value to determine how long the virtual user will remain active for. The length of time for activity will depend upon the performance of the Database Server under test. A higher performing server will process the defined number of transactions more quickly than a lower performing one. It is important to draw the distinction between the total_iterations value and the Iterations value set in the Virtual User Options window. The Iterations value in the Virtual User Options window determines the number of times that a script will be run in its entirety. The total_iterations value is internal to the TPROC-C driver script and determines the number of times the internal loop is iterated ie for {set it 0} {$it < $total_iterations} {incr it} { ... } In other words if total_iterations is set to 1000 then the executing user will log on once execute 1000 transactions and then log off. If on the other hand Iterations in the Virtual User Options window is set to 1000 and total_iterations in the script set to 1 then the executing user will log on execute one transaction and then log off 1000 times.You should ensure that the number of transactions is set to a suitably high vale to ensure that the virtual users do not complete their tests before the timed test is complete, doing so will mean the you will be timing idle virtual users and the results will be invalid.
Exit on ErrorExit on Error is shown as the parameter RAISEERROR in the Driver Script. RAISEERROR impacts the behaviour of an individual virtual user on detecting a database error. If set to TRUE on detecting an error the user will report the error into the HammerDB console and then terminate execution. If set to FALSE the virtual user will ignore the error and proceed with executing the next transaction. It is therefore important to be aware that if set to FALSE firstly if there has been a configuration error resulting in repeated errors then the workload might not be reported accurately and secondly you may not be aware of any occasional errors being reported as they are silently ignored.
Keying and Thinking TimeKeying and Thinking Time is shown as KEYANDTHINK in the Driver Script. This parameter will have the biggest impact on the type of workload that your test will take. Keying and thinking time is an integral part of a TPROC-C test in order to simulate the effect of the workload being run by a real user who takes time to key in an actual order and think about the output. If KEYANDTHINK is set to TRUE each user will simulate this real user type workload testing a workload scenario that will be closer to a real production environment. Whereas with KEYANDTHINK set to TRUE each user will execute maybe 2 or 3 transactions a minute setting KEYANDTHINK to FALSE each user will now execute tens of thousands of transactions a minute. If this parameter is set to TRUE you will need at least hundreds or thousands of virtual users and warehouses, if FALSE then you will need to begin testing with 1 or 2 Virtual Users, building from here up to a maximum workload with the number of warehouses set to a level where the users are not contending for the same data. The default mode is to run with KEYANDTHINK set to FALSE and this is the method that will drive the highest transaction rates. To run with KEYANDTHINK set to TRUE the event driven scaling feature has been introduced to scale up the number of sessions connecting to the system. This feature is activated by selecting the Asynchronous Scaling option (which will also enable Keying and Thinking time). When enabled you are able to configure multiple sessions per Virtual User. Each Virtual User will then manage multiple clients processing the Keying and Thinking time asynchronously. With this feature you are able to configure significantly more sessions than with a single Virtual User configuration.
Checkpoint/Vacuum when completeWhere available the database will trigger a checkpoint after the workload is complete to write out the modified data from the in-memory cache to the disk. if the database is correctly configured this will prevent this activity being conducted during a test to result in higher performance.
Minutes of Rampup TimeThe Minutes of Ramup Time is shown as rampup in the Driver Script. The rampup time defines the time in minutes for the monitoring virtual user to wait for the virtual users running the workload to connect to the database and build up the transaction rate by caching data in the database buffer cache before taking the first timed value and timing the test. The rampup time should be sufficiently long enough for a workload to reach a steady transaction rate before the first timed value is taken.
Minutes for Test DurationThe Minutes for Test Duration is shown as duration in the Driver Script. The test duration defines the time of the test measured as the time the monitor thread waits after the first timed value before taking the second one to signal the test is complete and the active virtual users to complete their workload.
Use All WarehousesBy default each Virtual User selects a home warehouse at random from at the start of a test and remains with that home warehouse. Therefore for example if there are 100 warehouses created and 10 virtual users selected to run the Driver Script then most of the activity will take place on 10 warehouse only. This option means that the Virtual Users select a new warehouse for each transaction from an available list divided between all Virtual Users at the start of the test therefore ensuring greater I/O activity.
Time ProfileWhen this option is selected client side time profiling will be conducted. There are two time profilers available, the xtprof profiler and the etprof profiler. The profiler chosen can be configured in the generic.xml file with xtprof profiling all virtual users and printing the timing output at the end of a run and the etprof profiler timing only the first virtual user but printing output at 10 second intervals.
Asynchronous ScalingEnable the event driven scaling feature to configure multiple client sessions per Virtual User. When selected this will also enable the Keying and Thinking Time option. As the keying and thinking time is managed asynchronously this option is not valid to be run without keying and thinking time. Asynchronous Scaling is also a feature that is appropriate to test connection pooling by scaling up the number of client sessions that connect to the database.
Asynch Client per Virtual UserConfigures the number of sessions that each Virtual User will connect to the database and manage. For example if there are 5 Virtual Users and 10 Asynchronous Clients there will be 50 active connections to the database.
Asynch Client Login DelayThe delay that each Virtual User will allow before logging on each asynchronous client.
Asynchronous VerboseReport asynchronous operations such as the time taken for keying and thinking time.
XML Connect PoolXML Connect Pool is intended for simultaneously testing multiple instances of related clustered databases and when selected the virtual user database connections will open a pool of connections defined in the database specific XML file for example mssqlscpool.xml for SQL Server located in the directory connectpool in the config directory. Note that each virtual user (or asynchronous client) will open and hold all of the defined connections. The monitor virtual user and each virtual user will also continue to open the main standalone database connection. The monitor virtual user will continue to report NOPM and TPM and the virtual users to extract the warehouse count from this standalone connection and therefore the reliance is on the database to accurately report cluster wide transactions and for the instances to have the same warehouse count. For verification of the results from the master connection when using connect pooling HammerDB will also report client side transactions. To use the XML Connect Pool the XML configuration file should be modified according to the cluster database names with each connection defined by the tag c1, c2 c3 etc respectively. Under the sprocs section in the XML file is defined which stored procedures will use which connections and what policy is to be used. The policy can be first_named, last_named, random or round_robin. For example with connections c1, c2 and c3 for neworder and a policy of round_robin the first neworder transaction would execute against connection c1, the second c2, the third c3 and the fourth c1. first_named uses the first given connection, last_named the last and random chooses a connection at random. stocklevel and orderstatus are read only stored procedures that may be run against read only cluster nodes. There is no restriction on the number of connections that may be opened per virtual user. For further information on the connections opened there is a commented information line in the driver script such as #puts "sproc_cur:$st connections:[ set $cslist ] cursors:[set $cursor_list] number of cursors:[set $len] execs:[set $cnt]" prior to the opening of the standalone connection that may be uncommented for more detail when the script is run.
ModeThe mode value is taken from the operational mode setting set under the Mode Options menu tab under the Mode menu. If set to Local or Primary then the monitor thread takes snapshots, if set to Replica no snapshots are taken. This is useful if multiple instances of HammerDB are running in Primary and Replica mode against a clustered database configuration to ensure that only one instance takes the snapshots.