Parameterization

Load Runner parameterization

Defining ParametersWhen you record a business process,
VuGen generates a script that containsthe actual values used during recording. Suppose you want to perform thescript’s actions (query, submit, and so forth) using different values fromthose recorded. To do this, you replace the recorded values with parameters.This is known as parameterizing the script.
This chapter describes:
➤ About Defining Parameters
➤ Understanding Parameter Limitations
➤ Creating Parameters
➤ Understanding Parameter Types
➤ Assigning Internal Data
➤ Selecting a File or Table as a Source for Parameter Values
➤ Defining Parameter Properties
➤ Using the Parameter List
➤ Customizing a Parameter Format
➤ Selecting an Update Method
➤ Importing Data from Existing Databases
➤ User-Defined Functions
➤ Setting the Parameter Brace and Storage Directory
The following information applies to all types of Vuser scripts except forGUI.VuGen User’s Guide •
Working with VuGen90
About Defining ParametersWhen you record a business process, VuGen generates a Vuser scriptcomposed of functions. The values of the arguments in the functions are theactual values used during the recording session.For example, assume that you recorded a Vuser script while operating a Webapplication. VuGen generated the following statement that searches alibrary’s database for the title “UNIX”:When you replay the script using multiple Vusers and iterations, you do notwant to repeatedly use the same value, UNIX. Instead, you replace theconstant value with a parameter:web_submit_form("db2net.exe",ITEMDATA,"name=library.TITLE","value=UNIX",ENDITEM,"name=library.AUTHOR","value=",ENDITEM,"name=library.SUBJECT","value=",ENDITEM,LAST);;web_submit_form("db2net.exe",ITEMDATA,"name=library.TITLE","value={Book_Title}",ENDITEM,"name=library.AUTHOR","value=",ENDITEM,"name=library.SUBJECT","value=",ENDITEM,LAST);Chapter 7 • Defining Parameters91The resulting Vusers then substitute the parameter with values from a datasource that you specify. The data source can be either a file, or internallygenerated variables. For more information about data sources, see“Understanding Parameter Types” .
Parameterizing a Vuser script has two advantages:
➤ It reduces the size of the script.
➤ It provides the ability to test your script with different values.
For example,if you want to search a library’s database for several titles, you only need towrite the submit function once. Instead of instructing your Vuser to searchfor a specific item, use a parameter. During replay, VuGen substitutesdifferent values for the parameter.Parameterization involves the following two tasks:➤ Replacing the constant values in the Vuser script with parameters➤ Setting the properties and data source for the parametersUnderstanding Parameter LimitationsYou can use parameterization only for the arguments within a function. Youcannot parameterize text strings that are not function arguments. Inaddition, not all function arguments can be parameterized. For details onwhich arguments you can parameterize, refer to the Online Function Reference(Help > Function Reference).For example, consider the lrd_stmt function. The function has thefollowing syntax:The Online Function Reference indicates that you can parameterize only thempcText argument.lrd_stmt (LRD_CURSOR FAR *mptCursor, char FAR *mpcText, long mliTextLen,LRDOS_INT4 mjOpt1, LRDOS_INT4 mjOpt2, int miDBErrorSeverity);VuGen User’s Guide • Working with VuGen92A recorded lrd_stmt function could look like this:You could parameterize the recorded function to look like this:Note: You can use the lr_eval_string function to “parameterize” a functionargument that you cannot parameterize by using standard parameterization.In addition, you can use the lr_eval_string function to “parameterize” anystring in a Vuser script. For more information on the lr_eval_stringfunction, refer to the Online Function Reference.Creating ParametersYou create a parameter by specifying its name and type. There is no limit tothe number of parameters you can create in a Vuser script.To create a parameter:1 In Script View: Select a string and select Replace with a Parameter from theright-click menu.2 In Tree View: Select the step you want to parameterize, and selectProperties from the right-click menu. The appropriate properties dialog boxopens.Click the ABC icon that is beside the argument to be parameterized.lrd_stmt(Csr4, "select name from sysobjects where name =\"Kim\" ", -1,148, -99999, 0);lrd_stmt(Csr4, "select name from sysobjects where name =\"\" ",-1, 148, -99999, 0);Chapter 7 • Defining Parameters93The Select or Create Parameter dialog box opens.3 Type a name for the parameter in the Parameter name box, or select anexisting parameter name from the list.4 Select a parameter type from the Parameter type list. The available types areDate/Time, File, Group Name, Iteration Number, Load Generator Name,Random Number, Unique Number, User Defined Function, or Vuser ID. Forinformation on the parameter types, see “Understanding Parameter Types”on page 96.5 Click OK to close the Select or Create Parameter dialog box. VuGen replacesthe selected string in your script with the name of the parameter,surrounded by brackets.VuGen User’s Guide • Working with VuGen94In Tree view, VuGen replaces the ABC icon with the table icon. In theexample below, the original URL value, “http://www.merc-int.com/,” hasbeen replaced with the parameter {url}.Note that when parameterizing CORBA or General-Java Vuser scripts, youmust parameterize complete strings, not parts of a string.Note: The default parameter braces are either curly or angle brackets,depending on the protocol type. You can change the parameter braces fromthe Parameterization tab in the General Options dialog box (selectTools > General Options). For more information, see “Setting the ParameterBrace and Storage Directory” on page 126.Parameter name Table iconChapter 7 • Defining Parameters95Replacing Multiple OccurrencesYou can replace selected or all occurrences of the string with the newparameter.To replace multiple occurrences of the string with the same parameter:1 select the parameter and choose Replace More Occurrences from the rightclickmenu. The Search and Replace dialog box opens.The Find What box displays the value you want to replace. The Replace Withbox displays the parameter name in brackets.2 Select the appropriate check boxes for matching whole words or case. Tosearch with regular expressions (., !, ?, etc.) select the Regular Expressionscheck box. For more information, see “,” on page 535.3 Click Replace or Replace All.Note: Use caution when using Replace All, especially when replacingnumber strings. VuGen changes all occurrences of the string.4 To replace a string with a previously defined parameter, enter Script view.Right-click on the string and select Use Existing Parameters. The UseExisting Parameters submenu opens.Select a parameter from the Use Existing Parameters submenu, or chooseSelect from Parameter List to open the Parameter List dialog box.VuGen User’s Guide • Working with VuGen96Note: Using the Parameter List is convenient when you want to replace astring with a previously defined parameter and, at the same time, view ormodify that parameter’s properties. For details on using the Parameter List,see “Using the Parameter List” on page 119.Restoring Original StringsVuGen lets you undo the parameterization by restoring the originallyrecorded string.To restore a parameter to its original value:1 In Script view, right-click on the parameter and select Restore OriginalValue.2 In Tree view, right-click on the step and click the table icon. and select UndoParameter from the pop-up menu. The original value is restored.Understanding Parameter TypesWhen you define a parameter’s properties, you specify the source for theparameter data. You can specify any one of the following data source types:Assigning Internal Data Data that is generated internally by the Vuser.This includes Date/Time, Group Name,Iteration Number, Load Generator Name,Random Number, Unique Number, and VuserID.Data Files and Data Tables Data that is contained in a file—either anexisting file or one that you create withVuGen or MS Query.User-Defined Functions Data that is generated using a function froman external DLL. For more information aboutuser-defined functions, see “Using theParameter List” on page 119.Chapter 7 • Defining Parameters97Assigning Internal DataInternal data is generated automatically while a Vuser runs. The followingsections describe the various types of internal data:➤ Date/Time➤ Group Name➤ Iteration Number➤ Load Generator Name➤ Random Number➤ Unique Number➤ Vuser ID➤ User-Defined FunctionsDate/TimeDate/Time replaces the parameter with the current date and/or time. Tospecify a date/time format, you can select a format from the menu list orspecify your own format. The format should correspond to the date/timeformat recorded in your script. To create a new format, enter the format inthe Date/Time format box, and click Add format. To delete a format, selectit and click Delete format. To restore the formats, click Reset formats.VuGen lets you set an offset for the date/time parameter. For example, if youwant to test a date next month, you set the date offset to 30 days. If youwant to test your application for a future time, you specify a time offset. Youcan specify a forward, future offset (default) or a backward offset, a date ortime that already passed. In addition, you can instruct VuGen to use datevalues for work days only, excluding Saturdays and Sundays.The following table describes the date/time symbols:Symbol Descriptionc complete date and time in digits#c complete date as a string and timeH hours (24 hour clock)VuGen User’s Guide • Working with VuGen98I hours (12- hour clock)M minutesS secondsp AM or PMd daym month in digits (01-12)b month as a string - short format (e.g. Dec)B month as a string - long format (e.g. December)y year in short format (e.g. 03)Y year in long format (e.g. 2003)Symbol DescriptionChapter 7 • Defining Parameters99To set the properties for Date/Time type parameters:1 Select one of the existing date/time formats or create a new format. You canview a sample of how VuGen will display the value, in the Sample Valuebox.2 To set a date or time offset, select Offset Parameter by and specify thedesired offset for the date and time values.To instruct VuGen to use working day dates only, excluding weekends, selectWorking days only. To indicate a negative offset to test a date prior to thecurrent, select Backward.3 Select an update method, instructing the Vuser when to update parametervalues—Each occurrence, Each iteration, or Once. For more information, see“Selecting an Update Method” on page 122.4 Click Close to accept the settings and close the Parameter Properties dialogbox.Group NameGroup Name replaces the parameter with the name of the Vuser Group. Youspecify the name of the Vuser Group when you create a scenario. When yourun a script from VuGen, the Group name is always None.VuGen User’s Guide • Working with VuGen100To set properties for the Group Name parameter type:1 Select one of the available formats or create a new one. You select a formatto specify the length of the parameter string. For details, see “Customizing aParameter Format” on page 121.2 Click Close to accept the settings and close the Parameter Properties dialogbox.Iteration NumberIteration Number replaces the parameter with the current iteration number.To set the properties for the Iteration Number parameter type:1 Select one of the available formats or create a new one. You select a formatto specify the length of the parameter string. For details, see “Customizing aParameter Format” on page 121.2 Click Close to save the settings and close the dialog box.Chapter 7 • Defining Parameters101Load Generator NameLoad Generator Name replaces the parameter with the name of the Vuserscript’s load generator. The load generator is the computer on which theVuser is running.To set the properties for the Load Generator Name parameter type:1 Select one of the available formats or create a new one. You select a formatto specify the length of the parameter string. For details, see “Customizing aParameter Format” on page 121.2 Click Close to save the settings and close the Parameter Properties dialogbox.VuGen User’s Guide • Working with VuGen102Random NumberRandom Number replaces the parameter with a random number. You set arange of random numbers by specifying minimum and maximum values.You can use the Random Number parameter type to sample your system’sbehavior within a possible range of values. For example, to run a query for50 employees, where employee ID numbers range from 1 through 1000,create 50 Vusers and set the minimum to 1 and maximum to 1000. EachVuser receives a random number, from within the range of 1 to 1000.To set the properties for Random Number type parameters:1 Enter a range defining the set of possible parameter values. You specifyminimum and maximum values for the range of random numbers.2 Select a Number format, indicating the length of the unique number.Specify %01lu for one digit,%01lu for two digits, etc. You can view a sampleof how VuGen will display the value, in the Sample Value box.3 Select an update method, instructing the Vuser when to update parametervalues—Each occurrence, Each iteration, or Once. For more information, see“Selecting an Update Method” on page 122.4 Click Close to accept the settings and close the Parameter Properties dialogbox.Chapter 7 • Defining Parameters103Unique NumberUnique Number replaces the parameter with a unique number. You specify astart number and a block size.When you use a Unique Number parameter type, you specify a start numberand a block size. The block size indicates the size of the block of numbersassigned to each Vuser. Each Vuser begins at the bottom of its range andincrements the parameter value for each iteration. For example, if you setthe Start number at 1 with a block of 500, the first Vuser uses the value 1and the next Vuser uses the value 501, in their first iterations.The number of digits in the unique number string together with the blocksize determine the number of iterations and Vusers. For example, if you arelimited to five digits using a block size of 500, only 100,000 numbers (0-99,999) are available. It is therefore possible to run only 200 Vusers, witheach Vuser running 500 iterations.You can also indicate what action to take when there are no more uniquenumbers in the block: Abort Vuser, Continue in a cyclic manner, or Continuewith last value (default)You can use the Unique Number parameter type to check your system’sbehavior for all possible values of the parameter. For example, to perform aquery for all employees, whose ID numbers range from 100 through 199,create 100 Vusers and set the start number to 100 and block size to 100.Each Vuser receives a unique number, beginning with 100 and ending with199.VuGen User’s Guide • Working with VuGen104Note: VuGen creates only one instance of Unique Number type parameters.If you define multiple parameters and assign them the Unique Parametertype, the values will not overlap. For example, if you define two parameterswith blocks of 100 for 5 iterations, the Vusers in the first group use 1, 101,201, 301, and 401. The Vusers in the second group use 501, 601, 701, 801,and 901.To set the properties for a Unique Number type parameter:1 Enter a start number and the desired block size. For example, if you want500 numbers beginning with 1, specify 1 in the Start box and 500 as a blocksize.2 Select a Number format, indicating the length of the unique number.Specify %01d for one digit, %01d for two digits, etc. You can view a sampleof how VuGen will display the value, in the Sample Value box.3 Select an update method, instructing the Vuser when to update parametervalues—Each occurrence, Each iteration, or Once. For more information, see“Selecting an Update Method” on page 122.4 Indicate what to do when there are no more unique values, in the When outof values box: Abort Vuser, Continue in cyclic manner, or Continue with lastvalue. Note, that when scheduling a scenario in the Controller, the Whenout of values option only applies for the Run for HH:MM:SS option in theSchedule Builder’s Duration tab. It is ignored for the Run until Completionoption.5 Click Close to accept the settings and close the Parameter Properties dialogbox.Chapter 7 • Defining Parameters105Vuser IDVuser ID replaces the parameter with the ID assigned to the Vuser by theController during a scenario run. Note that this is not the ID that appears inthe Vuser window—it is a unique ID number generated at runtime. Whenyou run a script from VuGen, the Vuser ID is always -1.To set the properties for the Vuser ID parameter type:1 Select one of the available formats or create a new one. You select a formatto specify the length and structure of the parameter string. For details, see“Customizing a Parameter Format” on page 121.2 Click Close to accept the settings and close the Parameter Properties dialogbox.User-Defined FunctionsA user-defined function replaces the parameter with a value returned from afunction located in an external DLL.Before you assign a user-defined function as a parameter, you create theexternal library (DLL) with the function. The function should have thefollowing format:The arguments sent to this function are both NULL.__declspec(dllexport) char *(char *, char *)VuGen User’s Guide • Working with VuGen106When you create the library, it is recommended that you use the defaultdynamic library path. That way, you do not have to enter a full path namefor the library, but rather, just the library name. The Virtual User Generatorbin directory is on the default dynamic library path. You can add yourlibrary to this directory.The following are examples of user-defined functions:When you select the User-Defined Function type, the user-defined functionproperties tab opens:To set the properties for user-defined functions:1 Specify the function name in the Function Name box. Use the name of thefunction as it appears in the DLL file.2 In the Library Names section, specify a library in the relevant Library box. Ifnecessary, locate the file using the Browse command.__declspec(dllexport) char *UF_GetVersion(char *x1, char *x2) {return"Ver2.0";}__declspec(dllexport) char *UF_GetCurrentTime(char *x1, char *x2) {time_t x = tunefully); static char t[35]; strcpy(t, ctime( &x)); t[24] = '\0';return t;}Chapter 7 • Defining Parameters1073 Select an update method for the values. For more information on updatemethods for user-defined functions, see “Selecting an Update Method” onpage 122.Selecting a File or Table as a Source for Parameter ValuesA very common method for using parameters, is instructing Vusers to takevalues from an external file or a data table.Data FilesData files hold data that a Vuser accesses during script execution. Data filescan be local or global. You can specify an existing ASCII file, use VuGen tocreate a new one, or import a database. Data files are useful if you havemany known values for your parameter.The data in a data file is stored in the form of a table. One file can containvalues for many parameters. Each column holds the data for one parameter.Column breaks are marked by a delimiter, for example, a comma.In the following example, the data file contains ID numbers and first names:For details on setting parameter properties for data files, see “Selecting a Fileor Table as a Source for Parameter Values” on page 107. details on importinga table from a database, see “Importing Data from Existing Databases,” onpage 123.Note: When working with languages other than English, save the parameterfile as a UTF-8 file. In the Parameter Properties window, click Edit inNotepad. In Notepad, save the file as a text file with UTF-8 type encoding.id,first_name120,John121,Bill122,TomVuGen User’s Guide • Working with VuGen108Data TablesThe Table type is meant for applications that you want to test by filling intable cell values. Whereas the file type uses one cell value for each parameteroccurrence, the table type uses several rows and columns as parametervalues, similar to an array of values. Using the table type, you can fill in anentire table with a single command. This is common in SAPGUI Vuserswhere the sapgui_fill_data function fills the table cells.For more information on setting the properties for file and table data types,see the following sections:➤ Selecting or Creating a Data File or Table➤ Setting the Properties for File Type Parameters➤ Setting the Properties for Table Type ParametersSelecting or Creating a Data File or TableTo set the data type, select the parameter in your script and chooseParameter properties from the right-click menu to open the ParameterProperties dialog box. You can also set the data from the Parameter Listdialog box (Vuser > Parameter List).To select a source file or table for your data:1 Right click on a parameter and choose Parameter Properties. VuGen displaysthe original value of the argument in the first column of the table.Chapter 7 • Defining Parameters1092 To add additional columns to the table, choose Add Column. The Add newcolumn dialog box opens. Enter a column name and click OK.3 To add additional rows to the table, choose Add Row. Click within any cellto enter a value.4 To edit the data file from within Notepad, click Edit with Notepad. Notepadopens with the parameter’s name in the first row and its original value inthe second row. Enter additional column names and values into the fileusing a delimiter such as a comma or a tab to indicate a column break. Begina new line for each table row (for each new row of data).5 To create a new table, click Create Table. VuGen creates a new table withone cell. Add columns and rows as described above.VuGen User’s Guide • Working with VuGen1106 To open a data file, type the name of a .dat file in the File path box or clickBrowse to specify the file location of an existing data file. By default, all newdata files are named parameter_name.dat and stored in the script’s directory.VuGen opens the data file and displays the first 100 rows. To view all of thedata, click Edit in Notepad and view the data in a text editor.You can also specify a global directory. Note that global directories areprovided only for backward compatibility with earlier versions of VuGen.For more information, see “Global Directory” on page 128.7 To import data, click Data Wizard and follow the wizard’s instructions. Formore information, see “Importing Data from Existing Databases,” onpage 123.After creating table or file data, you set the assignment properties. Theproperties specify the columns and rows to use, and whether to use the datarandomly or sequentially. You set the properties separately for the File andTable type parameters.Note: You can also set the properties for a parameter from the Parameter Listdialog box. In the left pane, select the parameter and then specify itsproperties in the right pane.Chapter 7 • Defining Parameters111Setting the Properties for File Type ParametersAfter you select a source of data, you set the assignment properties for yourfile. These properties instruct VuGen how to use the data. For example, theyindicate which columns, how often to use new values, and what do to whenthere are no more unique values.To set the file type parameter properties:1 Specify the column in the table that contains the values for your parameter.In the Select Column section, specify a column number or name.To specify a column number, select By number and the column number. Thecolumn number is the index of the column containing your data. Forexample, if the data for the parameter is in the table’s first column, select 1.To specify a column name, select By name and choose the column namefrom the list. The column is the first row of each column (row 0). If columnnumbers might change, or if there is no header, use the column name toselect a column.2 In the Column delimiter box of the File Format section, enter the columndelimiter—the character used to separate the columns in the table. You canspecify a comma, tab, or space.3 In the First data line box of the File Format section, select the first line ofdata to be used during Vuser script execution. The header is line 0. To beginwith the first line after the header, specify 1. If there is no header, specify 0.4 Select an option from the Select next row list to instruct the Vuser how toselect the table data during Vuser script execution. The options are:VuGen User’s Guide • Working with VuGen112Sequential, Random, or Unique. For more information, see “Choosing anAssignment Method for File or Table Type Parameters,” on page 115.5 Choose an update option from the Update Value on list. The choices areEach Iteration, Each Occurrence, and Once. For more information, see“Selecting an Update Method,” on page 122.6 If you chose Unique as the Select next row option:When out of values: Specify what to do when there is no more unique data:Abort the Vuser, Continue in a cyclic manner, or Continue with last value.Allocate Vuser values in the Controller: Indicate whether you want tomanually allocate data blocks for the Vusers. You can allow the Controller toautomatically allocate a block size or you can specify the desired number ofvalues. Choose Automatically allocate block size or Allocate x values foreach Vuser. For the second option, specify the number of values to allocate.Chapter 7 • Defining Parameters113Setting the Properties for Table Type ParametersAfter you select a table of data, you set its assignment properties. Theseproperties instruct VuGen how to use the table data. For example, theyindicate which columns and rows to use, how often to use them, and whatdo to when there are no more unique values.To set the table type parameter properties:1 Specify the columns in the table that contains the values for your parameter.In the Columns section, specify which columns you want to use.To choose all columns, select Select all columns.To specify one or more columns by their number, select Columns by numberand enter the column numbers separated by commas or a dash. The columnnumber is one-based. For example, if the data for the parameter is in thetable’s first column, select 1.2 In the Column delimiter drop-down box, select the column delimiter—thecharacter used to separate the columns in the table. The available delimitersare a comma, tab, or space.3 In the Rows section, specify how many rows to use per iteration in the Rowsper iteration box. Note that this only relevant when the Update value onfield is set to Each iteration. If Update value on is set to Once, then the samerows will be used for all iterations.VuGen User’s Guide • Working with VuGen1144 In the First line of data box, select the first line of data to be used duringscript execution. To begin with the first line after the header, enter 1. Todisplay information about the table, including how many rows of data areavailable, click Table information.5 Specify a row delimiter for your data presentation in the Rows delimiter forlog display box. This delimiter is used to differentiate between rows in theoutput logs. If you enable parameter substitution logging, VuGen sends thesubstituted values to the Execution log. The row delimiter character in theExecution log, indicates a new row.6 In the When not enough rows box, specify a handling method when thereare not enough rows in the table for the iteration. For example, assume thatthe table you want to fill has 3 rows, but your data only has two rows.Choose Parameter will get less rows than required to fill in only two rows.Choose Use behavior of “Select Next Row” to loop around and get the nextrow according the method specified in the Select next row box—randomlyor sequentially.7 Select an option from the Select next row list to instruct the Vuser how toselect the table data during Vuser script execution. The options are:Sequential, Random, or Unique. For more information, see “Choosing anAssignment Method for File or Table Type Parameters,” on page 115.8 Choose an update option from the Update value on list. The choices areEach Iteration and Once. For more information, see “Selecting an UpdateMethod,” on page 122.If you chose Unique as the Select next row option, choose the relevantoptions:When out of values: Specify how to proceed when there is no more uniquedata: Abort the Vuser, Continue in a cyclic manner, or Continue with last value.Allocate Vuser values in the Controller: Indicate whether you want tomanually allocate data blocks for the Vusers. You can allow the Controller toautomatically allocate a block size or you can specify the desired number ofvalues. Choose Automatically allocate block size or Allocate x values foreach Vuser. For the second option, specify the number of values to allocate.Chapter 7 • Defining Parameters1159 Choosing an Assignment Method for File or Table Type ParametersWhen using values from a file, VuGen lets you specify the way in which youassign values to the parameters. The available methods are:➤ Sequential➤ Random➤ UniqueSequentialThe Sequential method assigns parameter values to a Vuser sequentially. As arunning Vuser accesses the data table, it takes the next available row of data.If you specify Each Iteration in the Update Value on list box, the Vuser takesthe next value from the data table for each iteration.If you specify Each Occurrence in the Update Value on list box, the Vusertakes the next value from the data table for each occurrence of theparameter, even if it is within the same iteration.If you specify Once in the Update Value on list box, the value assigned in thefirst iteration is used for all subsequent iterations for each Vuser.For example, assume that your table has the values shownin the table at left.If you selected Each Iteration, all the Vusers use Kim in thefirst iteration, David in the second iteration, Michael inthe third iteration, etc.If you selected Each Occurrence, all the Vusers use Kim inthe first occurrence, David in the second occurrence,Michael in the third occurrence, etc.If you specified Once, all Vusers take Kim for all iterations.If there are not enough values in the data table, VuGenreturns to the first value in the table, continuing in a loopuntil the end of the test.First NameKimDavidMichaelJaneRonAliceKenJulieVuGen User’s Guide • Working with VuGen116RandomThe Random method assigns a random value from the data table to eachVuser at the start of the test run.If you specify Each Iteration in the Update Value on list box, the Vuser takes anew random value from the data table for each iteration.If you specify Each Occurrence in the Update Value on list box, the Vusertakes a new random value from the data table for each occurrence of theparameter, even if it is within the same iteration.If you specify Once in the Update Value on list box, the random valueassigned in the first iteration is used for all iterations of that Vuser.When running a scenario, session step, or BPM profile, you can specify aseed number for random sequencing. Each seed value represents onesequence of random values used for test execution. Whenever you use thisseed value, the same sequence of values is assigned to the Vusers in thescenario. You enable this option if you discover a problem in the testexecution and want to repeat the test using the same sequence of randomvalues.For more information refer to the refer to the LoadRunner Controller, TuningConsole, Performance Center, or Application Management user guides.UniqueThe Unique method assigns a unique sequential value to the parameter foreach Vuser.If you specify Each Iteration in the Update Value on list box, the Vuser takesthe next unique value from the data table for each iteration.If you specify Once in the Update Value on list box, the unique valueassigned in the first iteration is used for all subsequent iterations of theVuser.If you specify Each Occurrence in the Update Value on list box, the Vusertakes a new unique value from the data table for each occurrence of theparameter, even if it is within the same iteration.Chapter 7 • Defining Parameters117For example, assume that your table has the valuesshown in the table at left.If you specified Each Iteration, for a test run of 3iterations, the first Vuser takes Kim in the first iteration,David in the second, and Michael in the third. Thesecond Vuser takes Jane, Ron, and Alice. The third Vuser,Ken, Julie, and Fred.If you specified Once, the first Vuser takes Kim for alliterations, the second Vuser takes David for all iterations,etc.Make sure there is enough data in the table for all theVusers and their iterations. If you have 20 Vusers and youwant to perform 5 iterations, your table must contain atleast 100 unique values.If there are not enough values in the data table, you can instruct VuGenhow to proceed: Abort the Vuser, Continue in a cyclic manner, or Continue withlast value. If you choose to continue with the last value, the Vuser uses thedata from the last line of the table for all subsequent iterations.Suppose you want to allocate values for each Vuser, and you do not wantthose values shared between Vusers. To accomplish this, you instruct VuGento allocate a specific number of values for each Vuser in the Allocate VuserValues in the Controller section. By default, VuGen automatically allocatesthe necessary number of values for the Vusers.To track this occurrence, enable the Extended Log > Parameter Substitutionoption in the Log Run-Time settings. When there is not enough data,VuGen writes a warning message to the Vuser log "No more unique valuesfor this parameter in table ".First NameKimDavidMichaelJaneRonAliceKenJulieFredVuGen User’s Guide • Working with VuGen118Defining Parameter PropertiesAfter you create a parameter, you define its properties. A parameter’sproperties define the data source for the parameter during script execution.For a description of the properties, see “Understanding Parameter Types,” onpage 96To define a parameter’s properties:1 In Script view, select the parameter. Choose Parameter Properties from theright-click menu.2 In Tree view, right-click the step containing the parameter whose propertiesyou want to define, and select Properties. The properties dialog box for theselected step opens.3 Click the table icon beside the parameter whose properties you want todefine, and select Parameter Properties from the pop-up menu.Chapter 7 • Defining Parameters119The Parameter Properties dialog box opens and displays the properties forthe current parameter type. In the following example, the properties of a filetype parameter are displayed.4 Enter the properties of the parameter. For more information, see“Understanding Parameter Types” on page 96.5 Click Close to close the Parameter Properties dialog box.Using the Parameter ListUse the Parameter List to examine all of the parameters, create newparameters, delete parameters, or change the properties of an existingparameter.VuGen User’s Guide • Working with VuGen120To use the Parameter List:1 Click the Parameter List button or select Vuser > Parameter List. Select aparameter to show its properties. In the following example, the properties ofa Date/Time type parameter are displayed.2 To create a new parameter, click New. The new parameter appears in theparameter tree with a temporary name.Type a name for the new parameter, and press Enter.Note: Do not name a parameter unique, since this name is used by VuGen.Set the parameter’s type and properties, and then click OK to close theParameter List dialog box.Chapter 7 • Defining Parameters121Note: VuGen creates a new parameter, but does not automatically replaceany selected string in the script.3 To delete an existing parameter, select the parameter from the parametertree, click Delete, and confirm your action.4 To modify an existing parameter, select the parameter from the parametertree and edit the parameter’s type and properties.For more information on setting a parameter’s properties, see“Understanding Parameter Types” on page 96.Customizing a Parameter FormatFor most data types, you can customize a format for the parameter byselecting an existing format or specifying a new one. You should try to havethe parameter format match the recorded values. If the format of theparameter differs from the format of the original recorded value, the scriptmay not run correctly.The format specifies the length and structure of the resulting parameterstring. The resulting parameter string is the actual parameter value togetherwith any text that accompanies the parameter. For example, if you specify aformat of “%05s,” a Vuser ID of 5 is displayed as “00005,” padding the singledigit with four zeros. To pad the number with blank spaces, specify thenumber of spaces without a “0.” For example, %4s adds blank spaces beforethe Vuser ID so that the resulting parameter string is 4 characters long.You can specify a text string before and after the actual parameter value. Forexample, if you specify a format of “Vuser No: %03s,” a Vuser ID of 1 isdisplayed as “Vuser No: 001.”To add a format: Enter the format symbols in the editable box and clickAdd Format. When you add a format to the list, VuGen saves it with theVuser, making it available for future use.To delete a format: Select an existing format and click Delete format.VuGen User’s Guide • Working with VuGen122To restore the original formats: Click Reset formats.Selecting an Update MethodWhen using several of the parameter types, VuGen lets you specify theupdate method for the parameters. To set the update method, select amethod from the Update value on list. The available parameter updatemethods are:➤ Each Occurrence➤ Each Iteration➤ OnceEach OccurrenceThe Each occurrence method instructs the Vuser to use a new value for eachoccurrence of the parameter. This is useful when the statements using aparameter are unrelated. For example, for random data, it may be useful touse a new value for each occurrence of the parameter.Each IterationThe Each iteration method instructs the Vuser to use a new value for eachscript iteration. If a parameter appears in a script several times, the Vuseruses the same value for all occurrences of the parameter, for the entireiteration. This is useful when the statements using a parameter are related.Note: If you create an action block with parameters using its own iterationcount—if you instruct VuGen to update their values each iteration, it refersto the global iteration and not the block iteration. For more informationabout action blocks, see “Creating Action Blocks,” on page 143.OnceThe Once method instructs the Vuser to update the parameter value onlyonce during the scenario run. The Vuser uses the same parameter value forChapter 7 • Defining Parameters123all occurrences and all iterations of the parameter. This type may be usefulwhen working with dates and times.Importing Data from Existing DatabasesLoadRunner allows you to import data from a database for use withparameterization. You can import the data in one of two ways:➤ Creating a New Query➤ Specifying an SQL StatementVuGen provides a wizard that guides you through the procedure ofimporting data from a database. In the wizard, you specify how to importthe data—create a new query via MS Query or specifying an SQL statement.After you import the data, it is saved as a file with a .dat extension andstored as a regular parameter file.VuGen User’s Guide • Working with VuGen124To begin the procedure of importing a database, click Data Wizard in theParameter List dialog box (Vuser > Parameter List). The Database QueryWizard opens.Creating a New QueryYou use Microsoft’s Database Query Wizard to create a new query. Thisrequires the installation of MS Query on your system.To create a new query:1 Select Create new query. If you need instructions on Microsoft Query, selectShow me how to use Microsoft Query.2 Click Finish. If Microsoft Query is not installed on your machine,LoadRunner issues a message indicating that it is not available. Install MSQuery from Microsoft Office before proceeding.3 Follow the instructions in the wizard, importing the desired tables andcolumns.Chapter 7 • Defining Parameters1254 When you finish importing the data, choose Exit and return to Virtual UserGenerator and click Finish. The database records appear in the ParameterProperties box as a data file.To edit and view the data in MS Query, choose View data or edit inMicrosoft Query.5 Set the data assignment properties. See “Setting the Properties for File TypeParameters” on page 111.Specifying an SQL StatementTo specify a database connection and SQL statement:1 Select Specify SQL Statement. Click Next.2 Click Create to specify a new connection string. The Select Data Sourcewindow opens.3 Select a data source, or click New to create a new one. The wizard guides youthrough the procedure for creating an ODBC data source. When you arefinished, the connection string appears in the Connection String box.VuGen User’s Guide • Working with VuGen1264 In the SQL box, type or paste an SQL statement.5 Click Finish to process the SQL statement and import the data. The databaserecords appears in the Parameter Properties box as a data file.6 Set the data assignment properties. See “Setting the Properties for File TypeParameters” on page 111.Setting the Parameter Brace and Storage DirectoryYou can set the following parameterization options in VuGen:➤ Parameter Braces➤ Global DirectoryChapter 7 • Defining Parameters127Parameter BracesWhen you insert a parameter into a Vuser script, VuGen places theparameter braces on either side of the parameter name. The default bracesfor a Web or WAP script are curly brackets, for example,You can change the style of parameter braces by specifying a string of one ormore characters. All characters are valid with the exception of spaces.Note: The default parameter braces are angle or curly brackets, dependingon the Vuser type.To change the parameter brace style:1 Select Tools > General Options in VuGen. The General Options dialog boxopens.web_submit_form("db2net.exe",ITEMDATA,"name=library.TITLE","value={Book_Title}",ENDITEM,"name=library.AUTHOR","value=",ENDITEM,"name=library.SUBJECT","value=",ENDITEM,LAST);VuGen User’s Guide • Working with VuGen1282 Select the Parameterization tab and enter the desired brace.3 Click OK to accept the settings and close the dialog box.Global DirectoryThis option is provided only for backward compatibility with earlierversions of LoadRunner. In earlier versions, (4.51 and below), when youcreated a new data table, you specified local or global. A local table is savedin the current Vuser script directory and is only available to Vusers runningthat script. A global table is available to all Vuser scripts. The global directorycan be on a local or network drive. Make sure that the global directory isavailable to all machines running the script. Using the General Optionsdialog box, you can change the location of the global tables at any time.In newer versions of LoadRunner, you specify the location of the data tablein either the Parameter Properties or the Parameter List dialog box.LoadRunner is able to retrieve the data from any location that you specify—the default script directory or another directory on the network. For moreinformation, see “Data Files” on page 107.Chapter 7 • Defining Parameters129To set the global directory:1 Select Tools > General Options in VuGen. The General Options dialog boxopens.2 Select the Parameterization tab.3 Select the Define global data tables directory check box, and specify thedirectory containing your global data tables.4 Click OK to accept the settings and close the dialog box.VuGen User’s Guide • Working with VuGen1301318Correlating StatementsYou can optimize Vuser scripts by correlating statements. VuGen’sCorrelated Query feature allows you to link statements by using the resultsof one statement as input for another.This chapter describes:➤ About Correlating Statements➤ Using Correlation Functions for C Vusers➤ Using Correlation Functions for Java Vusers➤ Comparing Vuser Scripts using WDiff➤ Modifying Saved ParametersThe following information applies to all types of Vuser scripts except forGUI.About Correlating StatementsThe primary reasons for correlating statements are:➤ to simplify or optimize your codeFor example, if you perform a series of dependent queries one after another,your code may become very long. To reduce the size of the code, you cannest the queries, but then you lose precision and the code becomes complexand difficult to understand. Correlating the statements enables you to linkqueries without nesting.VuGen User’s Guide • Working with VuGen132➤ to generate dynamic dataMany applications and Web sites identify a session by the current date andtime. If you try to replay a script, it will fail because the current time isdifferent than the recorded time. Correlating the data enables you to savethe dynamic data and use it throughout the scenario run.➤ to accommodate unique data recordsCertain applications (for example databases) require the use of uniquevalues. A value that was unique during recording is no longer unique forscript execution. For example, suppose you record the process of opening anew bank account. Each new account is assigned a unique number which isunknown to the user. This account number is inserted into a table with aunique key constraint during recording. If you try to run the script asrecorded, it tries to create an account with the recorded number, rather thana new unique number. An error will result because the account numberalready exists.If you encounter an error when running your script, examine the script atthe point where the error occurred. In many cases, a correlated query willsolve the problem by enabling you to use the results of one statement asinput to another.The main steps in correlating a script are:1 Determine which value to correlate.For most protocols, you can view the problematic statements in theExecution log. You double-click an error message and jump directly to itslocation.Alternatively, you can use the WDiff utility distributed with VuGen todetermine the inconsistencies within your script. For more information, See“Comparing Vuser Scripts using WDiff” on page 136.2 Save the results.You save the value of a query to a variable using the appropriate function.The correlating functions are protocol-specific. Correlation function namesusually contain the string save_param, such as web_reg_save_param andlrs_save_param. Refer to the specific protocol chapters for an explanationChapter 8 • Correlating Statements133on how to perform correlation. In several protocols, such as database andWeb, VuGen automatically inserts the functions into your script.3 Reference the saved values.Replace the constants in the query or statement with the saved variables.Several protocols have built-in automatic or partially automated correlation:➤ For Java language Vusers, see Chapter 15, “Correlating Java Scripts.”➤ For Database Vusers, see Chapter 19, “Correlating Database Vuser Scripts.”➤ For Web Vusers, see Chapter 40, “Configuring Correlation Rules for WebVuser Scripts.”➤ For COM Vusers, see Chapter 26, “Understanding COM Vuser Scripts.”Using Correlation Functions for C VusersTo correlate statements for protocols that do not have specific functions,you can use the C Vuser correlation functions. These functions can be usedfor all C-type Vusers, to save a string to a parameter and retrieve it whenrequired. For similar functions for Java, Corba-Java, or RMI-Java Vusers, see“Using Correlation Functions for Java Vusers” on page 135.For additional information about the syntax of these functions, refer to theOnline Function Reference.lr_eval_string Replaces all occurrences of a parameter withits current value.lr_save_string Saves a null-terminated string to a parameter.lr_save_var Saves a variable length string to a parameter.VuGen User’s Guide • Working with VuGen134Using lr_eval_stringIn the following example, lr_eval_string replaces the parameter row_cntwith its current value. This value is sent to the output window usinglr_output_message.Using lr_save_stringTo save a NULL terminated string to a parameter, use lr_save_string. To savea variable length string, use lr_save_var and specify the length of the stringto save.In the following example, lr_save_string assigns 777 to a parameter emp_id.This parameter is then used in another query or for further processing.lrd_stmt(Csr1, "select count(*) from employee", -1, 1 /*Deferred*/, …);lrd_bind_col(Csr1, 1, &COUNT_D1, 0, 0);lrd_exec(Csr1, 0, 0, 0, 0, 0);lrd_save_col(Csr1, 1, 1, 0, "row_cnt");lrd_fetch(Csr1, 1, 1, 0, PrintRow2, 0);lr_output_message("value: %s", lr_eval_string("The row count is:"));lrd_stmt(Csr1, "select id from employees where name='John'",…);lrd_bind_col(Csr1,1,&ID_D1,...);lrd_exec(Csr1, ...);lrd_fetch(Csr1, 1, ...);/* GRID showing returned value "777" */lr_save_string("777", "emp_id");Chapter 8 • Correlating Statements135Using Correlation Functions for Java VusersTo correlate statements for Java, CORBA-Java, and RMI-Java Vusers, you canuse the Java Vuser correlation functions. These functions may be used for allJava type Vusers, to save a string to a parameter and retrieve it whenrequired.When recording a CORBA-Java or RMI-Java script, VuGen performscorrelation internally. For more information see Chapter 15, “CorrelatingJava Scripts.”Using the Java String FunctionsWhen programming Java Vuser scripts, you can use the Java Vuser stringfunctions to correlate your scripts.In the following example, lr.eval_int substitutes the variable ID_num withits value, defined at an earlier point in the script.In the following example, lr.save_string assigns John Doe to the parameterStudent. This parameter is then used in an output message.lr.eval_string Replaces a parameter with its current value.lr.eval_data Replaces a parameter with a byte value.lr.eval_int Replaces a parameter with an integer value.lr.eval_string Replaces a parameter with a string.lr.save_data Saves a byte as a parameter.lr.save_int Saves an integer as a parameter.lr.save_string Saves a null-terminated string to a parameter.lr.message(" Track Stock: " + lr.eval_int(ID_num));lr.save_string("John Doe", "Student");// ...lr.message("Get report card for " + lr.eval_string(""));classroom.getReportCardVuGen User’s Guide • Working with VuGen136Comparing Vuser Scripts using WDiffA useful tool in determining which values to correlate is WDiff. This utilitylets you compare recorded scripts and results to determine which valuesneed to be correlated.If you are working with other protocols, you can view the Execution log todetermine where the script failed and then use the WDiff utility to assist youin locating the values that need to be correlated.To use WDiff effectively, you record the identical operation twice, andcompare the scripts (or data files for Tuxedo, WinSock, and Jolt). WDiffdisplays differences in yellow. Note that not all differences indicate a valueto correlate. For example, certain receive buffers that indicate the time ofexecution do not require correlation.To search for correlations using WDiff:1 Record a script and save it.2 Create a new script and record the identical operations. Save the script.3 Select the section you want to compare (Actions, data.ws, and so forth).4 Select Tools > Compare with Vuser. The Open Test box opens.5 Specify a Vuser script for comparison (other than the one in the currentVuGen window) and click OK. WDiff opens and the differences between theVuser scripts are highlighted in yellow.Chapter 8 • Correlating Statements1376 To display the differences only, double-click in the WDiff window.7 Determine which values need to be correlated.Note that in the above example, WDiff is comparing the data.ws from twoWinsock Vuser scripts. In this instance, the value to be correlated is the PIDfor the clock processes, which differs between the two recordings.To continue with correlation, refer to the appropriate section:➤ For COM Vusers, see Chapter 26, “Understanding COM Vuser Scripts.”➤ For Database Vusers, see Chapter 19, “Correlating Database VuserScripts.”➤ For Java language Vusers, see Chapter 15, “Correlating Java Scripts.”➤ For Tuxedo Vusers, see Chapter 62, “Developing Tuxedo Vuser Scripts.”➤ For Web Vusers, see Chapter 40, “Configuring Correlation Rules for WebVuser Scripts.”➤ For WinSock Vusers, see Chapter 22, “Working with Window SocketsData.”PID 1PID 2VuGen User’s Guide • Working with VuGen138Modifying Saved ParametersAfter you save a value to a parameter, you may need to modify it beforeusing it in your script. If you need to perform arithmetical operations on aparameter, you must change it from a string to an integer using the atoi oratol C functions. After you modify the value as an integer, you must convertit back to a string to use the new variable in your script.In the following WinSock example, the data at offset 67 was saved to theparameter, param1. Using atol, VuGen converted the string to a long integer.After increasing the value of param1 by one, VuGen converted it back to astring using sprintf and saved it as a new string, new_param1. The value ofthe parameter is displayed using lr_output_message. This new value may beused at a later point in the script.lrs_receive("socket2", "buf47", LrsLastArg);lrs_save_param("socket2",NULL, "param1", 67, 5);lr_output_message ("param1: %s", lr_eval_string(""));sprintf(new_param1, "value=%ld", atol(lr_eval_string("")) + 1);lr_output_message("ID Number:"%s" lr_eval_string("new_param1"));1399Configuring Run-Time SettingsAfter you record a Vuser script, you configure the run-time settings for thescript. These settings specify how the script behaves when it runs.This chapter describes:➤ About Run-Time Settings➤ Configuring Run Logic Run-Time Settings (multi-action)➤ Pacing Run-Time Settings➤ Configuring Pacing Run-Time Settings (multi-action)➤ Setting Pacing and Run Logic Options (single action)➤ Configuring the Log Run-Time Settings➤ Configuring the Think Time Settings➤ Configuring Additional Attributes Run-Time Settings➤ Configuring Miscellaneous Run-Time Settings➤ Setting the VB Run-Time SettingsThe following information applies to all types of Vuser scripts except forGUI.About Run-Time SettingsAfter you record a Vuser script, you can configure its run-time settings. Therun-time settings define the way that the script runs. These settings arestored in the file default.cfg, located in the Vuser script directory. Run-timesettings are applied to Vusers when you run a script using VuGen or theController.VuGen User’s Guide • Working with VuGen140Configuring run-time settings allows you to emulate different kinds of useractivity. For example, you could emulate a user who responds immediatelyto output from the server, or a user who stops and thinks before eachresponse. You can also configure the run-time settings to specify how manytimes the Vuser should repeat its set of actions.You use the Run-Time Settings dialog box to display and configure the runtimesettings tree. You can open these settings in one of the following ways:➤ Click the Run-Time Settings button on the VuGen toolbar.➤ Press the keyboard shortcut key F4.➤ Choose Vuser > Run-Time Settings.You can also modify the run-time settings from the LoadRunner Controller.Click the Design tab and click the Run-Time Settings button.Note: Vuser scripts have individual run-time setting defaults for VuGen andthe Controller, to support the debugging environment of VuGen and theload testing environment of the Controller.These are the default settings for Vuser scripts in VuGen and the Controller:Think Time: Off in VuGen and replay as recorded in the Controller.Log: Standard in VuGen and off in the Controller.Download non-HTML resources: Enabled in VuGen and the Controller.The General run-time settings described in this chapter, apply to all types ofVuser scripts. They include:➤ Run Logic (Iterations)➤ Pacing➤ Log➤ Think Time➤ MiscellaneousChapter 9 • Configuring Run-Time Settings141For protocols that do NOT support multiple actions, such as WinSocket andDatabase (Oracle 2-tier, Sybase, MSSQL, etc.), the Iteration and Pacingoptions are both handled from the Pacing tab. Many protocols haveadditional run-time settings. For information about the specific run-timesettings for these protocols, see the appropriate sections.Configuring Run Logic Run-Time Settings (multi-action)Note: The following section only applies to protocols that work withmultiple actions. If the Run Logic node exists under the run-time settings, itis a multiple action protocol. For single action protocols, see “Setting Pacingand Run Logic Options (single action)” on page 148.Every Vuser script contains three sections: vuser_init, Run (Actions), andvuser_end. You can instruct a Vuser to repeat the Run section when you runthe script. Each repetition is known as an iteration.The vuser_init and vuser_end sections of a Vuser script are not repeated whenyou run multiple iterations.VuGen User’s Guide • Working with VuGen142Open the Run-Time Settings and select the General:Run Logic node.Number of Iterations: The number of iterations. LoadRunner repeats all ofthe Actions the specified number of times.If you specify a scenario duration in the Controller’s Scheduling settings, theduration setting overrides the Vuser iteration settings. This means that if theduration is set to five minutes (the default setting), the Vusers will continueto run as many iterations as required in five minutes, even if the run-timesettings specify only one iteration.When you run scripts with multiple actions, you can indicate how toexecute the actions, and how the Vuser executes them:Action Blocks: Action blocks are groups of actions within your script. Youcan set the properties of each block independently—its sequence, iterations,and weighting.Sequence: You can set the order of actions within your script. You can alsoindicate whether to perform actions sequentially or randomly.Iterations: In addition to setting the number of iterations for the entire Runsection, you can set iterations for individual actions or action blocks. This isuseful, for example, in emulating a commercial site where you performmany queries to locate a product, but only one purchase.Chapter 9 • Configuring Run-Time Settings143Weighting: For action blocks running their actions randomly, you can setthe weight or percentage of each action within a block.Creating Action BlocksAction blocks are groups of actions within the Vuser script. You can createseparate action blocks for groups of actions, adding the same action toseveral blocks. You can instruct VuGen to execute action blocks orindividual actions sequentially or randomly. In the default sequential mode,the Vuser executes the blocks or actions in the order in which they appear inthe iteration tree view.In the following example, Block0 performs a deposit, Block1 performs atransfer, and Block2 submits a balance request. The Login and Logout actionsare common to the three blocks.You configure each block independently—its sequence and iterations.To configure actions and action blocks:1 Create all of the desired actions through recording or programming.2 Open the Run-Time setting. Select the General:Run Logic node.3 Add a new action block. Click Insert Block. VuGen inserts a new Actionblock at the insertion point with the next available index (Block0, Block1,Block2).VuGen User’s Guide • Working with VuGen1444 Add actions to the block. Click Insert Action. The Select Actions list opens.5 Select an action to add to the block and click OK. VuGen inserts a newaction into the current block or section.6 Repeat step 3 for each action you want to add to the block.7 To remove an action or an action block, select it and click Delete.8 Click Move Up or Move Down to modify an item’s position.9 Click Properties to set the number of iterations and run logic of the actions.The Run Properties dialog opens.10 Select Sequential or Random from the Run Logic list, indicating to VuGenwhether to run the actions sequentially or randomly.11 Specify the number of iterations in the Iterations box. Note that if youdefine parameters within the action block, and you instruct VuGen toupdate their values each iteration, it refers to the global iteration—not theindividual block iteration.Chapter 9 • Configuring Run-Time Settings14512 Click OK.13 For blocks with Random run logic, set the weighting of each action. Rightclickan action and choose Properties. The Action Properties dialog opens.Specify the desired percent for the selected block or action. In the RandomPercents box, specify a percentage for the current action. The sum of allpercentages must equal 100.14 Repeat the above steps for each element whose properties you want to set.Pacing Run-Time SettingsNote: The following section only applies to protocols that work withmultiple actions. If the Run Logic node exists under the run-time settings, itis a multiple action protocol. For single action protocols, see “Setting Pacingand Run Logic Options (single action)” on page 148.The Pacing Run-Time settings let you control the time between iterations.The pace tells the Vuser how long to wait between iterations of your actions.You instruct the Vusers to start each iteration using one of the followingmethods:➤ As soon as the previous iteration ends.➤ After the previous iteration ends with a fixed/random delay of …➤ At fixed/random intervals, every …/ to … seconds.As soon as the previous iteration ends: The new iteration begins as soon aspossible after the previous iteration ends.VuGen User’s Guide • Working with VuGen146After the previous iteration ends with a fixed or random delay of …: Startseach new iteration a specified amount of time after the end of the previousiteration. Specify either an exact number of seconds or a range of time. Forexample, you can specify to begin a new iteration at any time between 60and 90 seconds after the previous iteration ends.The actual amount of time that the Vuser waits between the end of oneiteration and the start of the next one appears in the Execution Log whenyou run the script.At fixed or random intervals, every … [to …] seconds: You specify the timebetween iteration—either a fixed number of seconds or a range of secondsfrom the beginning of the previous iteration. For example, you can specifyto begin a new iteration every 30 seconds, or at a random rate ranging from30 to 45 seconds from the beginning of the previous iteration. Eachscheduled iterations will only begin when the previous iteration iscomplete.The actual amount of time that the Vuser waits between the end of oneiteration and the start of the next one, appears in the Execution Log whenyou run the script. Each scheduled iteration will only begin when theprevious iteration is complete.For example, assume that you specify to start a new iteration every fourseconds:➤ If the first iteration takes three seconds, the Vuser waits one second.➤ If the first iteration takes two seconds to complete, the Vuser waits twoseconds.➤ If the first iteration takes 8 seconds to complete, the second iteration willstart 8 seconds after the first iteration began. LoadRunner displays amessage in the Execution Log to indicate that the iteration pacing couldnot be achieved.For further instruction about setting the Pacing options, see “ConfiguringPacing Run-Time Settings (multi-action)” on page 147.Chapter 9 • Configuring Run-Time Settings147Configuring Pacing Run-Time Settings (multi-action)You use the Pacing options to pace your actions by setting the time intervalsbetween iterations.To set the pacing between iterations:1 Open the Run-Time Settings and select the General:Pacing node.2 In the Start New Iteration section, select one of the following options:➤ As soon as the previous iteration ends➤ After the previous iteration ends➤ At fixed or random intervals3 For the After the previous iteration ends option:➤ Select a delay type: fixed or random.➤ Specify a value for fixed, or a range of values for the random delay.4 For the At … intervals option:➤ Select a interval type: fixed or random.➤ Specify a value for fixed, or a range of values for the random interval.5 Click OK.VuGen User’s Guide • Working with VuGen148Setting Pacing and Run Logic Options (single action)Note: The following section only applies to protocols that work with singleactions, and not multiple actions. If there is a Pacing node and not a RunLogic node under the General run-time settings, it is a single actionprotocol.You can instruct a Vuser to repeat the Action section when you run thescript. Each repetition is known as an iteration. The vuser_init and vuser_endsections of a Vuser script are not repeated when you run multiple iterations.If you specify a scenario duration in the Controller’s Scheduling settings,then the duration setting overrides the Vuser iteration settings. This meansthat if the duration is set to five minutes (the default setting), the Vusers willcontinue to run as many iterations as required in five minutes, even if therun-time settings specify only one iteration.Chapter 9 • Configuring Run-Time Settings149To set the iteration and pacing preferences:1 Click the Run-Time Settings button on the VuGen toolbar or select Vuser >Run-Time Settings. Click the Pacing node to display the iteration andpacing options.2 Specify the number of iterations in the Iteration Count box. LoadRunnerrepeats all of the Actions the specified number of times.3 In the Start New Iteration section, select one of the following options:➤ As soon as the previous iteration ends➤ After the previous iteration ends➤ At fixed or random intervals4 For the After the previous iteration ends option:➤ Select a delay type: fixed or random.➤ Specify a value for fixed, or a range of values for the random delay.5 For the At … intervals option:➤ Select a interval type: fixed or random.➤ Specify a value for fixed, or a range of values for the random interval.VuGen User’s Guide • Working with VuGen1506 Click OK.For an overview of the pacing options, see “Pacing Run-Time Settings,” onpage 145.Configuring the Log Run-Time SettingsDuring execution, Vusers log information about themselves and theircommunication with the server. In a Windows environment, thisinformation is stored in a file called output.txt in the script directory. InUNIX environments, the information is directed to the standard output.The log information is useful for debugging purposes.The Log run-time settings let you determine how much information islogged to the output. You can select Standard or Extended log, or you candisable logging completely. Disabling the log is useful when working withmany Vusers. If you have tens or hundreds of Vusers logging their run-timeinformation to disk, the system may work slower than normal. Duringdevelopment, enable logging so that you will have information about thereplay. You should only disable logging after verifying that the script isfunctional.Note: You can program a Vuser script to send messages to the output byusing the lr_error_message and lr_output_message functions.Chapter 9 • Configuring Run-Time Settings151Click the Run-Time Settings button on select Vuser > Run-Time Settings todisplay the Run-Time Settings dialog box. Select the General:Log node todisplay the log options.Enable LoggingThis option enables automatic logging during replay—VuGen writes logmessages that you can view in the Execution log. This option only affectsautomatic logging and log messages issued through lr_log_message.Messages sent manually, using lr_message, lr_output_message, andlr_error_message, are still issued.Log OptionsThe Log run-time settings allows you to adjust the logging level dependingon your development stage.You can indicate when to send log messages to the log: Send messages onlywhen an error occurs or Always send messages. During development, youcan enable all logging. Once you debug your script and verify that it isfunctional, you can enable logging for errors only.If you choose to send messages only when errors occur, also known as JIT,(Just in Time) messaging, you can set an advanced option, indicating thesize of the log cache. See “Setting the Log Cache Size” on page 153.VuGen User’s Guide • Working with VuGen152Setting the Log Detail LevelYou can specify the type of information that is logged, or you can disablelogging altogether.Note: If you set Error Handling to “Continue on error” in the General Run-Time Settings folder, error messages are still sent to the Output window.If you modify the script’s Log Detail Level, the behavior of the lr_message,lr_output_message, and lr_log_message functions will not change—theywill continue to send messages.Standard Log: Creates a standard log of functions and messages sent duringscript execution to use for debugging. Disable this option for large loadtesting scenarios.If the logging level is set to Standard, the logging mode is automatically setto JIT logging when adding it to a scenario.Extended Log: Creates an extended log, including warnings and othermessages. Disable this option for large load testing scenarios. If logging isdisabled or if the level is set to Extended, adding it to a scenario does notaffect the log settings.You can specify which additional information should be added to theextended log using the Extended log options:➤ Parameter substitution: Select this option to log all parameters assignedto the script along with their values. For more information onparameters, see Chapter 7, “Defining Parameters.”➤ Data returned by server: Select this option to log all of the data returnedby the server.➤ Advanced trace: Select this option to log all of the functions andmessages sent by the Vuser during the session. This option is useful whenyou debug a Vuser script.Chapter 9 • Configuring Run-Time Settings153The degree to which VuGen logs events (Standard, Parameter substitution,and so forth) is also known as the message class. There are five messageclasses: Brief, Extended, Parameters, Result Data, and Full Trace.You can manually set the message class within your script using thelr_set_debug_message function. This is useful if you to want to receivedebug information about a small section of the script only.For example, suppose you set Log run-time settings to Standard log and youwant to get an Extended log for a specific section of the script. You wouldthen use the lr_set_debug_message function to set the Extended messageclass at the desired point in your script. You must call the function again tospecify what type of extended mode (Parameter, Result Data, or Full Trace).Return to the Standard log mode by calling lr_set_debug_message,specifying Brief mode. For more information about setting the messageclass, refer to the Online Function Reference (Help > Function Reference).If the logging mode was set to Standard log, VuGen automatically sets thelogging mode to Just-In-Time logging when you copying a script to ascenario. If the logging mode was set to Extended, or if logging was disabled,copying the script to a scenario does not affect its logging settings.Setting the Log Cache SizeThe Advanced options for the Log Run-Time settings, let you indicate thesize of the log cache. The log cache stores raw data about the test execution,to make it available should an error occur. When the contents of the cacheexceed the specified size, it deletes the oldest items. The default size is 1KB.The following is the sequence of the logging:1 You indicate to VuGen to log messages only when an error occurs, byselecting Send messages only when an error occurs.2 VuGen stores information about the test execution in the log cache withoutwriting it to a file. If this information exceeds 1 KB, it overwrites the oldestdata. The Execution Log tab also remains empty, since it is a dump of the logfile’s contents.3 When an error occurs (either an internal error or a programmed error usinglr_error_message), VuGen places the contents of the cache into the log fileVuGen User’s Guide • Working with VuGen154and Execution Log tab. This allows you to see the events that led up to the