LoadRunner® Client/Server
Database Driver Virtual Users
User’s Guide
LoadRunner Client/Server Database Drive Virtual Users© copyright 1996 by
Mercury Interactive Corporation.
All rights reserved. All text and figures included in this publication are the exclusive
property of Mercury Interactive Corporation, and may not be copied, reproduced, or used in
any way without the express permission in writing of Mercury Interactive . Information in
this document is subject to change without notice and does not represent a commitment on
the part of Mercury Interactive.
Patents pending.
LoadRunner, XRunner, and WinRunner are registered trademarks of Mercury Interactive
Corporation. TestDirector, TestSuite, Visual Testing, TSL and Context Sensitive are
trademarks of Mercury Interactive Corporation.
This document also contains registered trademarks, trademarks, and service marks that are
owned by their respective companies or organizations. Mercury Interactive Corporation
disclaim any responsibility for specifying which marks are owned by which companies or
organizations.
If you have any comments or suggestion regarding this document, please send them via
e-mail to documentation@mercury.co.il.
Mercury Interactive Corporation
470 Potrero Avenue
Sunnyvale, CA 94086
Tel. (408) 523-9900
Fax. (408) 523-9911
ii
Table of Contents
Welcome to the LoadRunner Client/Server Database Driver .............. v
Using This Guide ........................................................................................... v
LoadRunner Documentation Set ................................................................ vi
Online Resources ........................................................................................ vii
How to Use the Documentation ............................................................... vii
Typographical Conventions ..................................................................... viii
Chapter 1: LoadRunner Client/Server — Introduction and Process
Overview ........................................................................................................ 1
Chapter 2: Driver Software Installation .................................................. 7
Installing in a UNIX Platform ...................................................................... 7
Installing in Windows NT Platform ........................................................... 8
Installation Verification in a UNIX Platform ............................................. 9
Installation Verification in Windows NT Platform ................................ 11
Chapter 3: Recording Database Commands With SQL Inspectors .. 13
Chapter 4: Creating and Configuring a Virtual User .......................... 15
Creating a Vuser File in a UNIX Platform ............................................... 15
Configuring Replay in a UNIX Platform.................................................. 19
Creating a Vuser File in Windows NT Platform ..................................... 20
Configuring a Vuser File in Windows NT Platform............................... 22
Chapter 5: Running a Virtual User Program ........................................ 24
Chapter 6: Adding Think Times and Delays ....................................... 26
Files ................................................................................................................ 26
Configuration Parameters Which Affect Execution Speed ................... 27
iii
LoadRunner Client/Server Database Driver Virtual Users
Chapter 7: Varying Data of the Vusers (Data as Parameters) ........... 28
Changing the SQL in a UNIX Platform .................................................... 29
Changing the SQL on UNIX and Windows NT Platforms .................... 29
SOURCE ........................................................................................................ 30
VUSER ..................................................................................................... 30
GROUP .................................................................................................... 30
FILE Row Column Filename ................................................................ 31
UNIQ_#### [min] ................................................................................. 32
FUNCTION whichCase ........................................................................ 32
DATETIME format ................................................................................ 33
RANDOM [n] [m] .................................................................................. 33
Chapter 8: Using Rendezvous ................................................................. 34
Chapter 9: Adding Timed Transactions ................................................ 36
Chapter 10: Saving Result Rows to Files ............................................... 38
Chapter 11: Generating Unique IDs for Inserts................................... 42
Chapter 12: Correlating Queries ............................................................. 44
Appendix ...................................................................................................... 46
iv
Welcome to the LoadRunner
Client/Server Database Driver
Welcome to the LoadRunner Client/Server Database Driver Virtual
User, Mercury Interactive’s tool for testing a complete client/server
system. You can easily create effective test scenarios by following the
LoadRunner testing process. The LoadRunner Driver program is an
executable file that is ready to communicate with many popular
databases. The Driver program also needs the actual SQL calls made
between the client and the server. SQL calls are accomplished using
Mercury Interactive’s SQL Inspector product and other parameters
used by the Driver program (e.g., behavior of the Driver Virtual User,
replacement SQL data to vary input to the server along with other
parameters that are discussed in this document).
Using This Guide
This guide provides an overview of methods and processes that help
you effectively use LoadRunner and the Database Driver program,
one type of LoadRunner Virtual User. This guide has step-by-step
instructions to help you install and configure the software program on
UNIX or Microsoft Windows NT platforms. It also offers some
solutions to common issues with LoadRunner.
v
LoadRunner Client/Server Database Driver Virtual Users
Before you begin, refer to the LoadRunner Controller User’s Guide for
UNIX Platforms. It gives a general overview of automated load
testing, instructions on installing and setting up LoadRunner, creating
Load Test scenarios, and of LoadRunner terminology.
LoadRunner Documentation Set
Use this book in conjunction with other LoadRunner documents. (The
documents you receive with LoadRunner depends upon your virtual
user type.) LoadRunner documents include:
LoadRunner Controller User’s Guide describes how to create and
run LoadRunner scenarios in order to perform load testing.
GUI Virtual User User’s Guide describes how to create GUI Virtual
User scripts that can be incorporated into a LoadRunner scenario.
XRunner User’s Guide describes how to create GUI Vuser scripts for
X Windows applications on UNIX platforms.
TSL Reference Guide describes TSL functions that you can use in
Scenario and GUI Vuser (Virtual User) scripts.
DB Virtual User User’s Guide describes how to create DB Virtual
User scripts that can be incorporated into a LoadRunner scenario.
RTE Virtual User User’s Guide describes how to create RTE Virtual
User scripts that can be incorporated into a LoadRunner scenario.
Installation Guide explains how to install LoadRunner onto your
system. There are separate installation guides for each platform
supported by Mercury Interactive (for example Sun, HP, IBM, etc.).
Mercury Interactive SQL Inspector documentation explains how to
inspect or capture SQL information.
Product Release Notes provides last-minute news and information
about LoadRunner.
vi
Welcome to the LoadRunner Client/Server Database Driver
Online Resources
$$$ Please supply this information$$$
How to Use the Documentation
The following table lists the basic steps of the LoadRunner testing
process and indicates where to find relevant information. For an
overview of the LoadRunner testing process, refer to the LoadRunner
Controller User’s Guide.
The LoadRunner Testing Process
Refer to
Create Vuser Scripts for:
GUI Vusers
GUI Vuser’s Guide
DB Vusers
DB Vuser User’s Guide
RTE Vusers
RTE Vuser User’s Guide
Create Scenarios
Controller User’s Guide
Run Scenarios
Controller User’s Guide
Analyze Results
Controller User’s Guide
vii
LoadRunner Client/Server Database Driver Virtual Users
Typographical Conventions
This book uses the following typographical conventions:
viii
Bold
Bold text indicates functions names and the elements of
the functions that are to be typed in literally.
Italics
Italics text indicates variable names.
Helvetica
The Helvetica font is used for examples and statements
that are to be typed in literally.
[]
Square brackets enclose optional parameters.
{}
Curly brackets indicate that one of the enclosed values
must be assigned to the current parameter.
…
In a line of syntax, ellipses indicate that more items of
the same format may be included. In a program
example, ellipses are used to indicate lines of a program
that have been intentionally omitted.
1
LoadRunner Client/Server —
Introduction and Process Overview
The Driver software simplifies the creation of a LoadRunner virtual
user. LoadRunner overcomes these traditional development obstacles:
ä
The virtual user developer had to understand the C programming
language.
ä
The virtual user developer had to compile the virtual user each
time a change was made.
ä
A new virtual user program had to be created for each type of
virtual user.
ä
Maintenance could be high on a suite of virtual users.
The Driver’s virtual user, db_Vuser, hides some of the development
complexity and while providing a large degree of functionality.
db_Vuser simplifies the creation of a LoadRunner virtual user by
obtaining all runtime information from configuration and data files.
You need to compile the driver program only when you first install it.
The following diagram shows the process for using the Driver
program.
1
LoadRunner Client/Server Database Driver Virtual Users
1. Collect all client
and SQL
information
2. Create a “vuser
action file”
3. Setup the vuser
configuration
files if needed
4. Test the DB vuser
LoadRunner Client/Server is a set of tools that provides a load on the
server under test. The following diagram shows the recommended
process for developing and using LoadRunner client/server.
2
1. Define objectives
and transactions
2 Create a
WinRunner script
3. Capture client
API calls
(SQL, etc...)
4. Convert client
API calls into a
usable format
5. Create virtual users
6. Define and create
a LoadRunner
scenario
7. Run the test with
LoadRunner/PC
and WinRunner
only
8. Run test again but
activate
LoadRunner
9. Analyze and
compare results
LoadRunner Client/Server — Introduction and Process Overview
1
Define the customer’s objectives and the transactions to be
measured. Transactions can include the duration of the logon, the
time required for a particular screen to appear, the time required
for data to arrive, and so forth. The transaction timings can be
measured at various levels. You can measure interface timings,
database responses, and network response, either individually or
collectively.
Interface timings indicate the time it takes for an event to occur as
seen from a user’s perspective. You can measure interface timings
with both LoadRunner/PC and with WinRunner.
Remember
Interface timings are dramatically affected by the type of machine on
which the client runs. Differences in CPU speed and memory, for
example, affect the timing results.
You can measure both server and network timings with
LoadRunner. LoadRunner sends commands to the server under
test and measures how long it takes for a response to return. This
type of transaction timing does not include any of the interface
timings. DB Vuser measures the total time to send a query to the
time is returns (from a database). All processing time (CPU, disk,
etc.) is already accounted for in the measurement. The timing does
not include time in the GUI, as we use SQL Inspector to “inspect or
capture” the actual SQL information and play this back on a UNIX
or NT machine.
Note: LoadRunner GUI Vuser test scripts do include the user interface
timings as this type of Vuser is testing through the GUI — an X
Window or PC client.
3
LoadRunner Client/Server Database Driver Virtual Users
2
Create a WinRunner script to measure each transaction. Use
WinRunner to record the user interactions with the interface. Be
sure to add start and end transactions to the script.
Remember
The script must be designed in a manner that allows it to be replayed
repeatedly without causing different results to appear.
3
Replay the WinRunner script and capture data for LoadRunner.
LoadRunner data can be collected from the Inspector utilities, from
some utility provided on the client side, or some other method.
4
Convert the collected data into a form usable by LoadRunner. The
conversion might be as simple as extracting the information
needed to reproduce the requests made by the client machine (the
converted data must be available on the UNIX side). You may
want to name the data file so that it indicates the type of
transaction occurring on the client side.
5
Create a LoadRunner virtual user program that uses the data
obtained from the client. You can use the client data in one of the
basic templates, create your own template, or use the driver
program.
The program you create represents the actions that occur on the
client side. Use meaningful names for any program that you create
so that the name indicates the type of action the program
performs.
Remember
Any timing or transaction measurements made using the Database
Vuser on the UNIX or NT platform does not include the amount of
time the GUI interface incurred since there is no interface. For this
time to be included, you can use the GUI Virtual User.
4
LoadRunner Client/Server — Introduction and Process Overview
6
After you create all the virtual users, create a scenario script that
replays the desired mix of users. The scenario script should help
meet the objectives stated in step 1.
You can use the scenario example located in the directory
$M_DRIVERROOT/scenario/ to help get you started.
7
Once the scenario script completes, examine how the client
application responds with no server or network load. Create a
baseline by running one or two of the LoadRunner/PC clients. Do
not start any LoadRunner users.
8
When you have a baseline, examine how the client application
responds with the server and network load. Start LoadRunner,
then run the LoadRunner/PC clients. The transaction timing
returned on the PC indicates the times that would occur if there
were some number of users using the system at the same time.
9
Compare the baseline results with the results under load. You can
compare the data obtained in the reports or use the graphs to
examine the collected data.
5
LoadRunner Client/Server Database Driver Virtual Users
6
2
Driver Software Installation
Be sure that you have installed first installed the full LoadRunner
before you install the driver utilities. (This document does not support
LoadRunner installation.) Full LoadRunner installation includes file
installation, running lr_verify successfully, and successfully
launching, and executing the bank scenario. Verify the connection to
the database by logging on with the database’s SQL tool. Proceed only
after this installation process in complete.
Installing in a UNIX Platform
If the driver/sub-directory is included in your LoadRunner
distribution, copy the sub-directory to a workspace so that you have
write permission. The workspace sub-directory also ensures that
future upgrades of LoadRunner do not destroy your driver data. The
following example shows how to copy driver/sub-directory to your
home directory.
cp -r driver $HOME
7
LoadRunner Client/Server Database Driver Virtual Users
If your LoadRunner distribution does not contain the driver/subdirectory software, or you are upgrading the drivers, place the driver
add-on file in a directory of your choice (<yourPath>.) (If you need
this file, call Mercury Interactive Technical Support at 408 523-4299.)
For example, this process could be as follows:
a) uncompress and extract the tar file
% mv driv###.tar.Z <yourPath>
% cd <yourPath>
% uncompress driver#.##.tar.Z
% tar -xvf driver#.##.tar
In your .cshrc file, set M_DRIVERROOT to your driver installation
and adjust <your Path> to include the bin directory. For example:
setenv M_DRIVERROOT <yourPath>/driver
setenv PATH $M_DRIVERROOT/bin:$PATH
Installing in Windows NT Platform
If the driver/sub-directory is included in your LoadRunner
distribution, copy the sub-directory to a workspace so future upgrades
of LoadRunner do not destroy your Driver data.
If your LoadRunner distribution does not contain the driver/subdirectory software, or you are upgrading the drivers, place the driver
add-on file in a directory of your choice. (If you need this file, call
Mercury Interactive Technical Support at 408 523-4299.) You can use a
zip archive extraction program such as winzip or pkunzip (the
password for the compressed file is “driver40”). To unzip the files,
issue the following command (assuming you are at a DOS prompt
and using pkzip).
\> move driv40.zip <yourPath>
\>pkunzip driv40.zip
8
Driver Software Installation
To set M_DRIVERROOT to your Driver installation and to adjust
the PATH environment variable:
1
Double click “Control Panel.”
2
Double click “System.”
3
Add M_DRIVERROOT.
value: <yourPath>\driver
4
Edit PATH.
value: <yourPath>\driver\bin:%path%
Installation Verification in a UNIX Platform
Installation verification consists of performing a minimal set of actions
in order to log on. During this process, you can completely configure a
virtual user at this time. Refer to Installing in a UNIX Platform on page
7 for installation information. To verify that the LoadRunner software
has been installed correctly, do the following steps:
1
Ensure that your PATH environment variable is set correctly
according to the instructions in Installing in a UNIX Platform on
page 7.
2
Use the following command to start the Driver User Interface:
%driverui
The system displays the “example” Virtual User Dialog Box.
Note: You can override the loading of “example” with any Vuser by
using the Vuser resource: Driverui.Vuser: MyVuser.
9
LoadRunner Client/Server Database Driver Virtual Users
3
Verify the logon by using the database’s interactive query tool to
log onto the database.
Sybase:
isql -Uuser -Ppasswd -Sserver
Oracle:
sqlplus user/passwd@server
sqlplus user/password@T:host:server)
4
Select Vuser  Configure from the driverui main menu bar and
the Configuration window opens.
5
From the list, select and edit the following variables:
database_user = <user>
database_password = <passwd>
database_server = <server>
Note: For an Oracle database, you may need to indicate the host to log
on in Step 5. If so, also edit the variable: database_host = <host>
6
Click OK to apply changes and close the window.
7
From the API option menu, select the replay database API. The
default is Oracle.
Note: You can override the API default by using the api resource:
Driverui.api: 0, where the 0 corresponds to the position in the menu.
0 = SybaseCT
1 = SybaseDB
2 = Oracle
4 = Informix
8
10
Change Think Time to some value long enough to view the
window. This is typically done to simulate a user reading or using
the information that appeared from a query.
Driver Software Installation
9
From the main menu bar choose Vuser  Run, or click the Run
button.
10 Verify that the virtual user terminal appears, and the output text
shows that the run ended successfully.
Note: The prebuilt db_Vuser program fails to logon to Oracle 7.1.3.2.0
on Solaris 2.4 (and possibly other versions/platforms.) In this case
db_Vuser needs to be re-compiled with the libraries at your site.
Installation Verification in Windows NT Platform
1
Ensure that your PATH environment variable is set correctly,
according to the instructions in Installing in Windows NT
Platform.on page 8 for installation information.
2
Start the Driver User Interface. You can
— Double-click the Driver icon in the LoadRunner program
group.
Or
— Double-click the driver.exe file from File Manager.
Or
— Enter driverui.exe at the DOS prompt.
3
In the master.cfg file, edit the following variables:
database_user = <user>
database_password = <passwd>
database_server = <server>
Verify this logon by using the database’s interactive query tool to
log on to the database (for example, Sybase: isql, Oracle: sqlplus).
4
Select the replay database API from the API menu.
11
LoadRunner Client/Server Database Driver Virtual Users
12
5
On the main menu bar, choose Vuser  Run.
6
Verify that the virtual user window appears and the output text
shows that the run ended successfully.
3
Recording Database Commands With
SQL Inspectors
When recording database commands, you can
ä
Use the Inspector product that corresponds to your database
protocol to capture a log file of the database traffic.
ä
Use “Extended” mode as the capture mode.
ä
Select the option to save SQL Inspector information to a file.
ä
Stop SQL Inspector to save the data to disk.
For convenience, copy the logs (or ftp the logs to UNIX in ASCII
mode) you plan to replay to $M_DRIVERROOT/sql directory.
Refer to the Mercury Interactive SQL Inspector documentation for more
information.
13
LoadRunner Client/Server Database Driver Virtual Users
14
4
Creating and Configuring a Virtual
User
Creating a Vuser File in a UNIX Platform
To create a Vuser file in a UNIX platform, do the following steps:
1
Start the LoadRunner Driver Utility.
% driverui
15
LoadRunner Client/Server Database Driver Virtual Users
2
Choose File  New. The system prompts you for a new Vuser
name. The list of actions, which appears on the right, is cleared
out.
3
Select an Action from the toggle buttons. An Action is DB Action,
Think Time, or Rendezvous. These buttons are located on the
upper left of the user interface.
4
Press one of the buttons that operate on the list. For example, Add
After.
An Action Detail window appears. Fill in different details
depending on which action you want.
All actions accept a free form text in the Comment: field.
DB Action
Click Get Action. A standard file dialog box
appears.
Select either an Inspector log file or a preprocessed .sql file. If an inspector log is selected,
it is automatically converted to a .sql file. In this
case, you will see a terminal window pop up
showing the conversion. Verify that conversion
was successful and close the window.
Optionally, enter a transaction name to time this
action.
To use the Parameterize SQL button, refer to
16
Creating and Configuring a Virtual User
Varying Data of the Vusers (Data as Parameters) on
page 28.
17
LoadRunner Client/Server Database Driver Virtual Users
5
18
Think Time
Enter a time in seconds. Optionally, select the
random toggle for a random number from 0 up
to the time you entered.
Rendezvous
Enter a name for the rendezvous.
Click OK and the action is added to the list on the main window.
Creating and Configuring a Virtual User
Configuring Replay in a UNIX Platform
To configure Replay in a UNIX platform, do the following steps:
1
From the driverui, with the appropriate Vuser opened, choose
Vuser  Configure and the Configuration window opens.
2
Edit any number of variables and click OK.
The Apply button also saves changes, but leaves the
Configuration window open. For a description of the
configuration variables, read the comments displayed in the user
interface, or view the $M_DRIVERROOT/Vusers/master.cfg file. A
copy of this file is included in the Appendix.
3
Select a variable from the list, or optionally edit the value in the
text field.
19
LoadRunner Client/Server Database Driver Virtual Users
4
Select the proper toggle button below the edit field.
ä
If you are editing a Master default, you can:
— Save the value as the new Master Default.
— Save the value for only the current Vuser to use.
— Save the value as a global override for ALL Vusers.
ä
If you are editing a specific Vuser configuration value, you can:
— Save the value for this Vuser.
— Delete the specific value and use the Master Default
instead.
— Save the value as a global override for ALL Vusers.
ä
If you are editing the override value, you can:
— Save the value as the new override for ALL Vusers.
— Delete the global override. All Vusers will fall back to either
a specific Vuser value if it is set, or to the Master Default.
Creating a Vuser File in Windows NT Platform
To create a Vuser file in an NT platform, do the following steps:
1
Ensure that your path environment variable is set correctly,
according to the instructions in Installing in Windows NT Platform
on page 8 for installation information.
2
Start the Driver User Interface. You can
— Double-click the Driver icon in the LoadRunner program
group.
or
— double-click the driver.exe file from File Manager
or
20
Creating and Configuring a Virtual User
— enter driverui.exe at the DOS prompt
You are presented with three files to edit:
$M_DRIVERROOT
/Vusers/master.cfg
This is the master configuration file. It
includes any configuration information
(including default parameters) that is
common to all virtual users. Any of the
same parameters can also be used in a
Vuser’s configuration file.
Review the master.cfg file for details about
valid configuration parameters if you are
not familiar with configuring a Vuser. (An
example master.cfg file is also included in the
Appendix.)
3
$M_DRIVERROOT
/Vusers/example.cfg
This is the Vuser configuration file. It
overrides the master settings for the Vuser
named “example.”
$M_DRIVERROOT
/Vusers/example
This is the Vuser action file. It defines what
files must be executed to complete the
example user action. Each data file you
replay can optionally have a LoadRunner
transaction associated with it. You can also
add think times, rendezvous, and so forth,
to this file.
After you have verified that the example runs (refer to Installation
Verification in Windows NT Platform on page 11 for details), choose
either File  Open Vuser or File  New Vuser.
Note: When creating a new Vuser, select a simple descriptive filename
for it (for example, for a Vuser named “deposit,” you would now be
editing files named master.cfg, deposit.cfg, and deposit). The name
cannot contain the period character.
21
LoadRunner Client/Server Database Driver Virtual Users
4
(Optional) Add the recorded “actions” you want this Vuser to
replay.
Configuring a Vuser File in Windows NT Platform
To configure a Vuser file in an NT platform, do the following steps:
1
Choose Vuser  Add Action from the main menu bar. You are
prompted for the name of an inspector log which you can enter a
log name manually, or select one from a dialog box. These logs
were transferred to the $M_DRIVERROOT/sql directory (refer to
Recording Database Commands With SQL Inspectors on page 13).
2
Click OK.
3
Enter a transaction name at the prompt and click OK, or click
Cancel for no transaction.
The appropriate line is added to the bottom of the Vuser Action
File.
4
(Optional) Add any hand-written SQL you want this Vuser to
replay. You can
— Enter any valid SQL into a new <action>.sql file, or
— Add any <action>.sql files you created to a new line in the
Vuser Action File.
For additional configuration, see page 2 for the list of topics covered in
this guide.
22
Creating and Configuring a Virtual User
23
5
Running a Virtual User Program
To test the program by running it from outside LoadRunner’s control,
do the following steps:
1
From the Driver UI, select the database API to use during replay
from the API menu.
2
Choose Vuser  Run or Vuser  Debug Run. Alternatively, you
can run the Vuser from the command line:
$M_DRIVERROOT/bin/<API>/db_Vuser -user <Vuser_action_file>
where <API> is
oci for Oracle
ctlib for SybaseCT
dblib for SybaseDB
esql for Informix
where <Vuser_action_file> is the name of the Vuser, such as
“example”.
Use the -debug flag to perform a debugging run from the
command line:
$M_DRIVERROOT/bin/oci/db_Vuser -user example -debug
24
Running a Virtual User Program
While testing the Vuser, set the configuration variables
extended_messages and basic_messages to “yes.” If the Vuser
program gives error output, correct the problem before running
the Vuser from the LoadRunner controller. In this case, set these
variables to “no” when running from the LoadRunner controller,
so that minimal output is written to disk.
25
6
Adding Think Times and Delays
The driver program supports the addition of think times in several
different places. You can add think times by editing the configuration
files master.cfg or Vuser.cfg, the Vuser action file, or SQL data files.
For UNIX systems, the user interface supports adding think times to
the Vuser’s list of actions (the Vuser action file).
The following paragraphs discuss the details of adding think times
manually.
Files
Random think times are specified with a tilde (~) and the maximum
number of seconds to wait. For example, ~3 tells LoadRunner to wait
from 1 to 3 seconds. Fixed think times are specified with an
ampersand (&) and the number of seconds to wait. For example, &3
tells LoadRunner to wait three seconds.
Both types of actions can be added to either the Vuser action file or the
SQL data file by inserting a line in the file where you want the delay to
occur. Putting these actions in the Vuser action file adds a think time
between processing of entire SQL data files. Putting the delays in the
SQL data file adds think times between processing of individual queries
within an SQL file. (The SQL data file is the result of the conversion
program on an Inspector log.)
26
Adding Think Times and Delays
Configuration Parameters Which Affect Execution Speed
These parameters affect the replay speed of the DB Vuser. Refer to
master.cfg file, or the Master Config File in the Appendix for details.
min_(max_)random_wait_before_load
min_(max_)random_wait_before_run
min_(max_)random_wait_time
ignore_think_times
iteration_seconds
27
7
Varying Data of the Vusers (Data as
Parameters)
SQL data captured from the client represents commands sent from the
client to the server. Executing the captured command a second time
results in the same action being repeated. If you cannot play an SQL
command twice or want to vary the parameters in an SQL command,
modify some of the values that were captured so that you do not need
multiple SQL files.
To change the SQL “on the fly,” substitute unique strings into the SQL
command in the SQL data files. The rest of this section uses the
example of adding a “flights” action to the Vuser Action File. The
syntax of the action is shown below.
flights.sql
FlightTransaction
28
Varying Data of the Vusers (Data as Parameters)
Changing the SQL in a UNIX Platform
To change the SQL in a UNIX platform, do the following steps:
1
From the user interface, select the list item that represents the
action you want to convert to a parameter.
2
Press Modify and the Action Detail window appears.
3
Press Parameterize SQL. Two edit windows appear: one for the
flights.sql and one for the replace file.
Note: You can change the default editor (vi) to another editor. For
example,
setenv DRIVER_EDITOR emacs
then restart the driverui.
Changing the SQL on UNIX and Windows NT Platforms
The recording of the Client Application produced by SQL Inspector
created a log of SQL commands with hard-coded or actual data.
Typically, one may need to replace this actual data with variable data.
To accomplish this task, replace the actual data with a unique string.
These strings get replaced at run-time with variable data from one of
the many data sources or files. The following example demonstrates
how this works.
Edit the $M_DRIVERROOT/sql/flights.sql file.
Change
select * from flights where fl_to = ‘LAX’ and fl_from = ‘BWI’
To
select * from flights where fl_to = ‘<To_City>’ and fl_from = ‘<From_City>’
The Vuser replaces the unique strings <To_City> and <From_City>
during run-time with varying data values. You supply a file that
describes where and how to get the data to substitute for each unique
string.
29
LoadRunner Client/Server Database Driver Virtual Users
Note: The Vuser’s configuration must identify this source file.
The syntax for describing the replace file is as follows (refer to
Appendix for the example Replace Master File,
$M_DRIVERROOT/files/replace):
replace_master_file = <full path of the file>
For this flight example, the replace file might look like this:
<To_City>
FILE RANDOM_LINE COL_1
$M_DRIVERROOT/files/cities
<From_City> FILE VUSER_ID_LINE ENTIRE_LINE
$M_DRIVERROOT/files/cities
The format of replace_master_file is:
variable SOURCE [specifiers]
where variable is any unique string name you want to replace.
SOURCE
VUSER
Replace occurrences variable with the Vuser number assigned by the
LoadRunner Controller. From the command line, the Vuser number is
0. Additional parameters are not used.
GROUP
Replace occurrences variable with the Group name assigned by the
LoadRunner Controller. From the command line, the Group name is
“None.” Additional parameters are not used.
30
Varying Data of the Vusers (Data as Parameters)
FILE Row Column Filename
Replace occurrences variable with a string read from a file. Three
specifier fields are required: row, column, and filename.
row
RANDOM_LINE
randomly picks a line from the file
SAVED_LINE
uses the most recently read line again. This command
is used to group data together. Example: your query
wants to pick a social security number and that
person’s name. Both are in a file, one in column 1 and
the other in column 2. SSN may be RANDOM_LINE,
but you need SAVED_LINE for the Name so they stay
grouped.
SEQUENTIAL
reads the file in sequential order
VUSER_ID_LINE
uses the line number that corresponds to the Vuser ID.
column
COL_#
columns of data are white-space delimited. # is a
column number.
ENTIRE_LINE
Substitute the whole line from file (including spaces),
not just a column.
filename
Full pathname of the file to use. Can contain $M_DRIVERROOT, which is
expanded. Two other keywords used include GROUP and VUSER. These are
substituted for the Vuser’s Group name and Vuser number. So,
$M_DRIVERROOT/files/GROUP/VUSER/datafile may expand to
/usr/lrunner/driver/files/None/0/datafile. This is important when you try to
correlate queries. Refer to Correlating Queries on page 44 for further
information.
31
LoadRunner Client/Server Database Driver Virtual Users
UNIQ_#### [min]
Replace occurrences variable with a unique number, where
#### is the total number of IDs (unique numbers) each Vuser will
need to complete all iterations of one run.
[Min] is the minimum ID to use.
For more information on IDs, refer to Generating Unique IDs for Inserts
on page 42.
FUNCTION whichCase
Replace occurrences variable with a string returned from a C function.
You supply a number, whichCase. This number is used in a switch
statement inside the C function, UserFunction, to determine which
block of user-defined code to execute. The db_Vuser calls
UserFunction (whichCase).
Edit userfunc.c and add your case to the switch statement. userfunc.c
already contains one case to model your new code after.
char *UserFunction (int whichCase)
{
static char replace[80];
/***************************************************************************
* Set a default replace string
***************************************************************************/
strcpy(replace, "<BAD SUBSTITUTION>");
switch (whichCase) {
case 0:
break;
}
return replace;
}
32
Varying Data of the Vusers (Data as Parameters)
DATETIME format
Replace occurrences variable with the current system date and/or
time. When format is specified, it is supported by the C function
strftime( ).
RANDOM [n] [m]
Replace occurrences variable with a pseudo-random number.
[n]
Used to set an upper limit in the range 0 to n-1.
[m]
If present with [n], [m] is used to set the upper bound of the range
n to m.
33
8
Using Rendezvous
Use the following commands to turn on the built-in rendezvous in the
configuration files.
rdz_name_each_action
rdz_name_each_iteration
where
rdz_name_each_action
makes rendezvous occur before each action
is executed in the Vuser action file. (An
action is all of the SQL commands in one
data file.)
rdz_name_each_iteration
makes rendezvous occur before each
iteration is executed. (A single iteration is all
of the SQL files listed in the Vuser action
file.)
You can manually insert other rendezvous anywhere within the Vuser
Action File or any of the SQL data files by adding the following
directive.
^REND[EZVOUS] = <RendName>
You can configure the rendezvous <RendName> in the LoadRunner
Controller scenario.
34
Varying Data of the Vusers (Data as Parameters)
35
9
Adding Timed Transactions
You can use two commands to turn on built-in transactions in the
configuration files. One command is a logon transaction that times the
logon process (logon_transaction_name); the other is a Vuser
transaction that times the entire run (vuser_transaction_name).
The action file lets you set a transaction for each .sql file (a converted
inspector log.) Within the “Action Detail” window (UNIX Database
Driver GUI), you can specify the transaction. Using the Database
Driver on Windows NT, you can add the transaction in the Vuser
Action File manually (refer to Appendix for more information).
If you want any other transactions, you can add them to the action file
or .sql files with the following directives:
^START = TranName
^END = TranName
36
Varying Data of the Vusers (Data as Parameters)
37
10
Saving Result Rows to Files
This feature is supported for OCI, UPI and CT-lib.
Use the ^SAVE directive to save all result rows to files or choose
specific queries that will save their result rows. The syntax of the
^SAVE directive is:
^SAVE = [ON | OFF ] filename
You can insert ^SAVE anywhere in the Vuser Action File (between
execution of entire xxx.sql files) or into the *.sql files themselves. The
following examples illustrate the use of this directive.
^SAVE = ON <filename>
Begin saving result rows of each query (a
counter is appended to the <filename>. For
example, filename.1, filename.2).
^SAVE = OFF
Suspend saving of result rows.
^SAVE = filename
Save only the next SQL statement results to
<filename>.
Before the data can be useful to the running Vuser, header
information, save all the result sets in a file separate from the data
rows. This header information is stored in <filename>.idx, the index
file.
38
Varying Data of the Vusers (Data as Parameters)
Save all files in the same sub-directory structure that LoadRunner uses
so that multiple groups and Vusers don’t overwrite each other. (For
example, $M_DRIVERROOT/files/GROUP/VUSER/<filename>,
where GROUP is the same as Sgroup in the LoadRunner scenario and
VUSER is the Vuser ID number.)
Example
Your SQL query for a flight reservation application selects all the
flights for a particular city on a particular airline where you vary the
departure and destination city. This mechanism requires a file
containing the different cities and a file with the different airports you
intend to substitute in the query. To get these files, find the queries
that retrieve this data, or create your own sql data file; then add the
^SAVE directive before the query. The next time this Vuser is
replayed, you will have your cities file. The syntax for this example is
as follows:
^SAVE = ON savefile
select distinct city from cities
select distinct airport from airports
^SAVE = OFF
The index file for this example is as follows:
$M_DRIVERROOT/files/group1/0/savefile.idx
city
--------------/usr/lrunner/driver/files/group1/0/savefile.1
airport
--------------/usr/lrunner/driver/files/group1/0/savefile.2
39
LoadRunner Client/Server Database Driver Virtual Users
You will most likely then rename savefile.1 to cities and savefile.2 to
the names of airports. Alternatively, you can create what is known as
correlated queries. These use the individual SAVE feature to produce
the cities and airports files. You need to do this if the data files are
generated during run-time so that the returned data can be used later
in other queries. The directives for this are shown below.
^SAVE = cities
select distinct city from cities
^SAVE = airports
select distinct airport from airports
Refer to Correlated Queries on page 44 for details on these types of
queries.
40
Varying Data of the Vusers (Data as Parameters)
41
11
Generating Unique IDs for Inserts
To keep insert statements from failing, you can use the FILE technique
described in Varying Data of the Vusers (Data as Parameters) on page 28
in order to get a different primary key for each row in a file.
Alternatively, you can set the SOURCE of the replace string to
UNIQ_#### instead of FILE.
The alternative sets aside #### IDs for one virtual user. For example,
if #### is 1000, Vuser 0 will use IDs 0-999. Vuser 1 will use 1000-1999,
and so forth. All iterations start with the lowest number and
increment by one. Therefore, if you plan 10,000 iterations, you need
#### to be at least 10,000.
Realize that this technique will not work if the table has rows with IDs
in the range indicated by #####. To avoid generating existing IDs, use
min option, as shown below (refer to UNIQ_#### [min] on page 32 for
details).
Variable UNIQ_### [min]
42
Varying Data of the Vusers (Data as Parameters)
Caution: Do not let the ID get too large. The maximum number that
the primary key can hold must be more than the result of the
following calculation:
total number of inserts in one iteration  number of iterations
the number of users + minimum ID value
Too large an ID causes a database error, trying to insert a number
which is too large for the Database field
Example
You want each Vuser to do up to 10,000 inserts. The table already has
some data in it; so don’t generate any IDs below 5,000. (Vuser 0 will
use 5000-14,999, and so forth.)
In the .sql file of this example, change the ID recorded to the string
“<unique_id>.“ Insert into Table1 values (<unique_id>, “name”, 1, 0).
In the replace file of this example, add <unique_id> (UNIQ_10000
5000).
43
12
Correlating Queries
Correlated queries use the result data from a previous query as input
to the current SQL statement. The techniques for creating correlated
queries are described in Saving Result Rows to Files on page 38 and
Varying Data of the Vusers (Data as Parameters) on page 28. After you
save the results from one query to a specific file, set up another SQL
statement to substitute one or more of its variables with data from this
file.
Example
In the first SQL call you select the employee's ID (and possibly other
data.) The next query is an "update" that needs to use the ID in the
where clause.
Using the ability to save results to a file, edit the *.sql file so the results
of the select statement will be saved to "idfile."
Next set up the update statement to read the ID from that same file. It
is important to remember that you are planning to run a multi-user
scenario. Because of this, the datafile "idfile" which contains the result
row is saved in a sub-directory based on the Group and Vuser ID. For
example, if the Group is "Withdraw" and this Vuser is 7, the file for
this Vuser will be saved in:
$M_DRIVERROOT/files/Withdraw/7/idfile
Naturally, the Group and Vuser ID will need to be substituted at runtime. The replace file supports two key words, GROUP and VUSER, to
handle this.
44
Varying Data of the Vusers (Data as Parameters)
The SQL file will look like this:
^SAVE = idfile
select ID, firstname, lastname from emp
update emp set salary = 50000 where id = <emp_id>
The "replace" file will include the following line:
<emp_id> FILE SEQUENTIAL COL_1 $M_DRIVERROOT/files/GROUP/VUSER/idfile
45
Appendix
Master Configuration File
(See: $M_DRIVERROOT/Vusers/master.cfg)
/*
username for logon.
Sybase logon: isql -Udatabase_user
Oracle logon: sqlplus database_user
*/
database_user = user
/*
password for logon.
Sybase logon: isql -Udatabase_user -Pdatabase_password
Oracle logon: sqlplus database_user/database_password
*/
database_password
=
/*
server for logon.
Sybase logon: isql -Udatabase_user -Pdatabase_password Sdatabase_server
Oracle logon: sqlplus
database_user/database_password@database_server
*/
database_server
= DBSERVER
/*
Database connection timeout
*/
database_timeout
= 30
46
Appendix
/*
Normally left BLANK.
For ORACLE, database_host is ONLY used for SQL*NET v1 style
logons.
(SCOTT/TIGER@T:database_host:SERVER)
It is the host the server is on.
For Sybase, this is not required for logon, it can be set to
show which host the CLIENT is
running on.
*/
database_host
=
/*
The name of the client application.
Sybase only...(not required for logon)
*/
database_app
=
/*
Which database to use.
Informix: Required
Sybase:
Optional
Oracle:
N/A
*/
database_use_database
=
/*
yes or no : whether Sybase CT-lib should use RPC
*/
ctlib_use_rpc
= no
/*
Replace File : Varying Data used by the Vuser
#############################################################
A file to list all strings you want to search for and replace
replace_master_file
= $M_DRIVERROOT/files/replace
*/
replace_master_file
=
/*
yes or no : whether debugging messages are printed.
This indicates the amount of information that you wish to appear
in the output window. Once you are ready to run a load test,
override these with 'no'.
*/
basic_messages
= yes
extended_messages
= yes
/*
The number of iterations to execute.
0 means the Vuser will run forever.
*/
47
LoadRunner Client/Server Database Driver Virtual Users
number_of_iterations
= 1
/*
Minimun time for an iteration.
An iteration is one processing of all actions listed for this
Vuser.
*/
iteration_seconds
= 0
/*
yes or no : whether to ignore think times
This ignores all manually added think times AND all recorded
think times in the ".sql" action files.
*/
ignore_think_time
= no
/*
Minimum wait time, in seconds, before loading.
This is used with maximum wait.
*/
min_random_wait_before_load = 0
/*
Maximum wait time, in seconds, before loading.
*/
max_random_wait_before_load = 0
/*
Minimum wait time, in seconds, before running.
This is used with maximum wait.
*/
min_random_wait_before_run = 0
/*
Minimum wait time, in seconds, before running.
This is used with maximum wait.
*/
max_random_wait_before_run = 0
/*
Iteration
If you do
blank.
Remember,
script if
*/
Rendezvous -- Rendezvous before each iteration.
not want the rendezvous to occur, leave the name
you should also define the rendezvous in the scenario
you specify a name here.
rdz_name_each_iteration
=
/*
Action Rendezvous -- Rendezvous before each action file is
executed.
48
Appendix
If you do not want the rendezvous to occur, leave the name
blank.
Remember, you should also define the rendezvous in the scenario
script if you specify a name here.
*/
rdz_name_each_action
=
49
LoadRunner Client/Server Database Driver Virtual Users
/*
load or run : when the logon should occur.
*/
logon_run_or_load
= load
/*
A file of SQL commands to be run during the logon.
Normally left BLANK. It is a full pathname of the file to
execute. Defaults to $M_DRIVERROOT/sql/ if no path is given.
*/
logon_sql_file
=
/*
The transaction name to be recorded when logging on.
If you do not want a transaction get recorded, leave the name
blank.
*/
logon_transaction_name
= T_logon
/*
Varying Logon User and Password
################################################################
#######
A file to use for the user name and password. The program will
use the
name and password on the line equal to the Vuser #. If there is
no
password, the default password from above will be used. The full
path
must be specified. $M_DRIVERROOT is the only allowed env. var.
The recommended location is the files/ sub-directory.
name_password_file
*/
name_password_file
= $M_DRIVERROOT/files/name.pw
=
/*
A transaction name for the entire run of the Vuser.
This will include any use think times.
*/
Vuser_transaction_name =
/*
yes or no : whether to have the Vuser exit or continue
when a database error occurs.
*/
exit_on_error
= no
50
Appendix
Virtual User Action File
(See: $M_DRIVERROOT/Vusers/example)
/*
The rendezvous 'rend_at_start' should be defined in the
controller to set the number of Vusers, timeout, etc.
*/
^REND = rend_at_start
/*
Random wait
*/
~3
/*
Execute the SQL in the file: example.sql
Time this transaction under the name Example_Tran
*/
example.sql
Example_Tran
/*
Fixed wait time of 1 second
*/
&1
51
LoadRunner Client/Server Database Driver Virtual Users
Example replace_master_file
(See: $M_DRIVERROOT/files/replace)
<CITY1> FILE RANDOM_LINE
$M_DRIVERROOT/files/cities
<CITY2> FILE RANDOM_LINE
$M_DRIVERROOT/files/cities
<CITY3> FILE SAVED_LINE
$M_DRIVERROOT/files/cities
<CITY4> FILE VUSER_ID_LINE
$M_DRIVERROOT/files/cities
<CITY5> FILE SEQUENTIAL
$M_DRIVERROOT/files/cities
<uniq> UNIQ_1000
25000
<num>
RANDOM
5 10
<date> DATETIME %D %Y
<VID>
VUSER
<GROUP> GROUP
52
ENTIRE_LINE
COL_1
COL_2
ENTIRE_LINE
COL_1
Appendix
SQL data files (*.sql)
These files generate automatically when you select an Inspector log
file to be added to the Vuser action file. A conversion program
processes the log and pulls out the SQL statements as well as
calculating think times and setting MAX_ROWS and/or
FETCH_ROWS. These files contain any of the directives described in
the Vuser action file.
Example:
#
# Comments are ignored
#
^REND = Rendezvous1
^MAX_ROWS = 1000
^FETCH_ROWS = 50
select * from flights
#
# Recorded User think time
&5
53