Command Line Parsing Functions: Page 1 of 337

Page 1 of 337
Command Line Parsing Functions

Click one of the following functions for more information:
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Command Line Parsing Functions
lr_get_attrib_double Returns the value of a double type command line parameter
lr_get_attrib_long Returns the value of a long integer type command line
parameter.
lr_get_attrib_string Returns a command line parameter string.
Page 2 of 337
Informational Functions
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Informational Functions
lr_end_timer Stops a timer.
lr_get_host_name Returns the name of the host executing the script.
lr_get_master_host_name Returns the name of the machine running the
LoadRunner
Controller .
lr_get_vuser_ip Returns the IP address of the current Vuser. Not applicable for
products that do not run Vusers.
lr_start_timer Starts a timer.
lr_user_data_point Records a user-defined data sample.
lr_user_data_point_ex Records a user-defined data sample and enables logging
option.
lr_user_data_point_instance Records a user-defined data sample and correlates
it to a
transaction instance.
lr_user_data_point_instance_ex Records a user-defined data sample and enables
logging
option.
lr_whoami Returns information about a Vuser executing the script. Not
applicable for products that do not run Vusers.
Page 3 of 337
Message Functions
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Message Functions
lr_debug_message Sends a debug message to the LoadRunner output window or
Application Management agent log file.
lr_error_message Sends an error message to the LoadRunner output window or
lr_get_debug_message Returns the current message logging settings.
lr_log_message Sends a message to the Vuser log file.
lr_message Sends a message to the log file and output window.
lr_output_message Sends a Vuser message to the log file and output window with
location information.
lr_set_debug_message Sets a message class for output messages.
lr_vuser_status_message Sends a message to the Vuser status area in the
LoadRunner
Controller.
Page 4 of 337
Run-Time Functions
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Run-Time Functions
lr_abort Aborts script execution.
lr_continue_on_error Specifies an error handling method.
lr_disable_ip_spoofing Disables IP Spoofing.
lr_enable_ip_spoofing Enables IP Spoofing.
lr_exit Exits from the script, action, or iteration.
lr_load_dll Loads an external DLL.
lr_param_increment Increments the value of a numerical parameter
lr_peek_events Checks for events.
lr_rendezvous Creates a rendezvous point in the Vuser script.
lr_rendezvous_ex Sets a rendezvous point in a Vuser script.
lr_think_time Pauses execution between commands in a script.
Page 5 of 337
String and Parameter Functions

HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > String and Parameter Functions
lr_advance_param Advances to the next available value in the parameter data file.
lr_checkpoint Validates the value of a parameter against an expected value
(checkpoint).
lr_convert_string_encoding Converts a string to a different encoding.
lr_decrypt Decrypts an encoded string.
lr_eval_string Returns the string argument after evaluating embedded parameters.
lr_eval_string_ext Creates a buffer and assigns it the input string after evaluating
embedded parameters.
lr_eval_string_ext_free Frees the buffer allocated by lr_eval_string_ext.
lr_next_row Advances to the next row in the parameter data file.
lr_param_increment Increments the value of a LoadRunner parameter.
lr_param_sprintf Writes formatted output to a parameter.
lr_param_unique Generates a unique string and assigns it to a parameter.
lr_paramarr_idx Returns the value of the parameter at a specified location in a
parameter array.
lr_paramarr_len Returns the number of elements in a parameter array.
lr_paramarr_random Returns the value of the parameter at a random location in a
parameter array
lr_save_datetime Saves the date and time into a parameter.
lr_save_int Saves an integer to a parameter.
lr_save_searched_string Searches for an occurrence of a string in a buffer and
saves a
portion of the buffer after that string to a parameter.
lr_save_string Saves a null terminated string as a parameter.
lr_save_var Saves a variable length string as a parameter.
Page 6 of 337
Transaction Functions
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Transaction Functions
lr_end_sub_transaction Marks the end of a sub-transaction.
lr_end_transaction Marks the end of a transaction.
lr_end_transaction_instance Marks the end of a transaction instance.
lr_fail_trans_with_error Sets the status of open transactions to LR_FAIL and
sends
an error message.
lr_get_trans_instance_duration Returns the duration of a transaction instance
specified by
its handle.
lr_get_trans_instance_status Returns the current status of a transaction
instance.
lr_get_trans_instance_think_time Gets the think time of a transaction instance
specified by
its handle.
lr_get_trans_instance_wasted_time Gets the wasted time of a transaction
instance by its
handle.
lr_get_transaction_duration Gets the duration of a transaction by its name.
lr_get_transaction_status Gets the current status of a transaction.
lr_get_transaction_think_time Gets the think time of a transaction by its name.
lr_get_transaction_wasted_time Gets the wasted time of a transaction by its
name.
lr_resume_transaction Resumes collecting transaction data.
lr_resume_transaction_instance Resumes collecting transaction instance data.
lr_set_transaction Create a transaction manually.
lr_set_transaction_instance_status Sets the status of a transaction instance.
lr_set_transaction_status Sets the status of open transactions.
lr_set_transaction_status_by_name Sets the status of a transaction.
lr_start_sub_transaction Marks the beginning of a sub-transaction.
lr_start_transaction Marks the beginning of a transaction.
lr_start_transaction_instance Starts a nested transaction specified by its parent's
handle.
lr_stop_transaction Stops the collection of transaction data.
lr_stop_transaction_instance Stops collecting data for a transaction specified by
its
handle.
lr_wasted_time Removes wasted time from all open transactions.
Page 7 of 337
Database Functions
These database functions can only be used with the Web Services protocol.
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Database Functions
lr_db_connect Connects to a database.
lr_db_disconnect Disconnects from a database.
lr_db_executeSQLStatement Submits an SQL statement to a database.
lr_db_dataset_action Performs an action on a dataset.
lr_db_getValue Retrieves a value from a dataset.
lr_db_dataset_action Validates database contents by setting checkpoints.
Page 8 of 337
Alphabetical Listing
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Alphabetical Listing
lr_abort Aborts script execution.
lr_advance_param Advances to the next available value in the parameter
data file.
lr_continue_on_error Specifies an error handling method.
lr_convert_string_encoding Converts a string to a different encoding.
lr_db_dataset_action Validates database contents by setting checkpoints.
lr_db_connect Connects to a database.
lr_db_dataset_action Performs an action on a dataset.
lr_db_disconnect Disconnects from a database.
lr_db_executeSQLStatement Submits an SQL statement to a database.
lr_checkpoint Validates the value of a parameter against an expected
value (checkpoint).
lr_db_getValue Retrieves a value from a dataset.
lr_debug_message Sends a debug message to the LoadRunner output or
lr_decrypt Decrypts an encoded string.
lr_disable_ip_spoofing Disables IP Spoofing.
lr_enable_ip_spoofing Enables IP Spoofing.
lr_end_sub_transaction Marks the end of a sub-transaction.
lr_end_transaction Marks the end of a LoadRunner transaction.
lr_end_transaction_instance Marks the end of a transaction instance.
lr_end_timer Marks the end of a sub-transaction.
lr_error_message Sends an error message to theLoadRunner output or
Application Management agent log file..
lr_eval_string Replaces a parameter with its current value.
lr_eval_string_ext Creates a buffer and assigns it the input string after
evaluating embedded parameters.
lr_eval_string_ext_free Frees the buffer allocated by lr_eval_string_ext.
lr_exit Exits from the script, action, or iteration.
lr_fail_trans_with_error Sets the status of open transactions to LR_FAIL and
sends
an error message.
lr_get_attrib_double Returns the value of a double type command line
parameter.
lr_get_attrib_long Returns the value of a long integer type command line
parameter.
lr_get_attrib_string Returns a command line parameter string.
lr_get_debug_message Returns the current message logging settings.
Page 9 of 337
lr_get_host_name Returns the name of the host executing the script.

lr_get_master_host_name Returns the name of the machine running the
LoadRunner
Controller.
lr_get_transaction_duration Gets the duration of a transaction by its name.
lr_get_transaction_status Gets the current status of a transaction.
lr_get_trans_instance_duration Returns the duration of a transaction by its
name.
lr_get_trans_instance_status Returns the current status of a transaction
instance.
lr_get_trans_instance_think_time Gets the think time of a transaction instance
specified by
its handle.
lr_get_trans_instance_wasted_time Gets the wasted time of a transaction
instance by its
handle.
lr_get_transaction_think_time Gets the think time of a transaction by its name.
lr_get_transaction_wasted_time Gets the wasted time of a LaoadRunner
transaction by its
name.
lr_get_vuser_ip Returns the IP address of the current Vuser. Not applicable
for products that do not run Vusers.
lr_load_dll Loads an external DLL.
lr_log_message Sends a message to the Vuser log file.
lr_message Sends a message to the output and log file.
lr_output_message Sends a message to the output and log file with location
information.
lr_next_row Advances to the next row in the parameter data file.
lr_param_increment Increments the value of a numerical parameter
lr_param_sprintf Writes formatted output to a parameter.
lr_param_unique Generates a unique string and assigns it to a parameter.
lr_paramarr_idx Returns the value of the parameter at a specified location
in a parameter array.
lr_paramarr_len Returns the number of elements in a parameter array.
lr_paramarr_random Returns the value of the parameter at a random location in
a parameter array
lr_peek_events Checks for events.
lr_rendezvous Creates a rendezvous point in the Vuser script.
lr_rendezvous_ex Sets a rendezvous point in a Vuser script.
lr_resume_transaction Resumes the collection of transaction data.
lr_resume_transaction_instance Resumes collecting transaction instance data.
lr_save_datetime Saves the date and time into a parameter.
lr_save_int Saves an integer to a parameter.
lr_save_searched_string Searches for an occurrence of a string in a buffer and
saves a portion of the buffer after that string to a
parameter
lr_save_string Saves a null-terminated string as a parameter.
lr_save_var Saves a variable length string as a parameter.
lr_set_debug_message Sets a message class for output messages.
Page 10 of 337
lr_set_transaction Create a transaction manually.

lr_set_transaction_status Sets the status of open transactions.
lr_set_transaction_status_by_name Sets the status of a transaction by its name.
lr_start_transaction Marks the beginning of a transaction.
lr_start_transaction_instance Marks the beginning of a transaction instance
lr_start_sub_transaction Marks the beginning of a sub-transaction.
lr_stop_transaction Halts the collection of transaction data.
lr_stop_transaction_instance Stops collecting data for a transaction instance
specified
by its handle.
lr_think_time Pauses execution between commands in a script.
lr_user_data_point Records a user-defined data sample.
lr_user_data_point_ex Records a user-defined data sample.
lr_user_data_point_instance Records a user-defined data sample and correlates
it to a
lr_user_data_point_instance_ex Records a user-defined data sample and
correlates it to a
lr_vuser_status_message Sends a message to the Vuser status area in the
Controller.
lr_wasted_time Removes wasted time from all open transactions.
lr_whoami Returns information about a Vuser executing the script
Page 11 of 337
lr_abort
Aborts the execution of a script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_abort
Return Values Parameterization
void lr_abort( );
Example See Also
Java Language
void lr.abort( );
Example See Also Java Syntax
The lr_abort function aborts the execution of a script . It stops the execution of the
Actions section,
executes the vuser_end section, and ends the execution. This function is useful when
you need to
manually abort a run as a result of a specific error condition. When you end a run
using this function,
the status is "Stopped."
Page 50 of 337
lr_advance_param
Advances to the next available parameter value.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_advance_param
int lr_advance_param ( const char *param);
Example See Also
Java Language
int lr.advance_param ( String parameter );
Visual Basic
function lr.advance_param ( ByVal parameter as string ) as integer
Example See Also Visual Basic Syntax
The lr_advance_param function causes the script to use the next available value of
the parameter.
If you are running multiple iterations, you can specify in the parameter properties to
advance
automatically to the next value for each iteration. Use this function within an
iteration to advance to
the next value.
The effect on other parameters in the same data file depends on the settings in the
Vuser parameter
list dialog. See the Example.
This function is not recorded—you insert it manually into your script.
param The name of the parameter in quotes (no brackets).
Page 51 of 337
lr_checkpoint
Validates the value of a parameter against an expected value (checkpoint).
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_checkpoint
int lr_checkpoint("StepName=<step_name>",
"ActualValue={<input_param>}",
"Compare=<operator>", "ExpectedValue={<checkpoint>}",
"StopOnValidationError=<error_code>", LAST);
Example See Also
The lr_checkpoint function validates the value of a parameter against a checkpoint
value.
If the validation fails, the script aborts or continues, depending on the values of the
StopOnValidationError argument and the Continue on Error? runtime setting. The
Continue on
Error? runtime setting takes precedence over the value of StopOnValidationError.
Operators are case-sensitive.
This function is not recorded. It can be added manually when enhancing the script.
StepName The name of the step, as it appears in the test tree. Any text can be used.
ActualValue Data to compare with the ExpectedValue argument. Can be a value or a
LoadRunner parameter.
Compare Operator used to compare the ActualValue and ExpectedValue values:
Equals
NotEquals
Contains
StartsWith
EndsWith
ExpectedValue Data to compare with the ActualValue argument. Can be a value or a
LoadRunner parameter.
StopOnValidationError Indication of whether all steps fail. Valid values:
false: Steps do not fail.
true: Steps fail.
LAST This delimiter marks the end of the argument list.
Page 52 of 337
lr_continue_on_error
Specifies an error handling method.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_continue_on_error
void lr_continue_on_error ( int value );
Example See Also
The lr_continue_on_error function specifies how to handle errors. You can choose
to continue
running if an error occurs, or to abort the run execution.
Normally, you specify how the test run component handles errors during script
execution using the
General section in VuGen's Runtime Settings dialog. By default, the script exits when
an error occurs.
To continue script execution even when errors occur, select the Continue on Error
check box in
VuGen's Runtime Settings.
However, you can control error handling for a specific segment of the script, by
inserting the
lr_continue_on_error function before and after the desired segment (see the
example for details).
In addition to the lr_continue_on_error statements, you can use severity levels to
control error
handling for database operation errors in LoadRunner.
value One of the Error Continuation Options.
Page 53 of 337
lr_convert_string_encoding
Converts a string to a different encoding.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_convert_string_encoding
int lr_convert_string_encoding ( const char *sourceString, const char
*fromEncoding,
const char *toEncoding, const char *paramName);
Example See Also
lr_convert_string_encoding converts a string encoding between the following
encodings: System
locale, Unicode, and UTF-8. The function saves the result string, including its
terminating NULL, in the
parameter paramName.
lr_convert_string_encoding is added manually to a script when needed. It is not
recorded.
Possi bl e val ues f or ' f r omEncodi ng' and ' t oEncodi ng' :
sourceString The string to convert
fromEncoding The encoding of the sourceString
toEncoding The encoding to convert of the string saved in parameter paramName
paramName The name of the parameter in which the destination string will be saved
Constant Value
LR_ENC_SYSTEM_LOCALE NULL
LR_ENC_UTF8 "utf-8"
LR_ENC_UNICODE "ucs-2"
Page 54 of 337
lr_db_connect
Connects to a database.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_connect
int lr_db_connect("StepName",
"ConnectionString=<connection_string>",
"ConnectionName=<connection_name>",
"ConnectionType=<connection_type>",
LAST);
Example See Also
The lr_db_connection function establishs the database connection used by other
database related
functions, such as lr_db_executeSQLStatement .
Tip: Use the Connection Dialog to create a database specific connection string. Select
the
Database: Connect option in the Add Step dialog box and enter the connection
parameters.
When specifying the connection string for a specific SQL Server instance, use the
server and instance
name in the data source, escaping the backslashes in the path. For example:
"Connect i onSt r i ng=Ser ver=soa-m16\ \ soa;Dat abase=. . .
When specifying the connection string using SQL Server 2005 Express, use the
server name syntax
<SQL Server 2005 Express installation>\SQLEXPRESS.
Add lr_db_connect to the vuser_init section of the script. Adding this function to
the Action section
can increase performance overhead during load testing.
ConnectionString A string indicating the database to which to connect and other
information
needed to establish the connection.
The syntax for the connection string varies depending on the data provider
specified with the ConnectionType argument. For example, to connect to an SQL
Server, ConnectionString could contain the value:
Dat a Sour ce=mySer ver Addr ess; I ni t i al Cat al og=myDat abase
I d=myUser ; Passwor d=myPasswor d;
Note that the equal signs are part of the connection string.
The password cannot be encrypted.
ConnectionName A logical name for the connection.
ConnectionType Type of data provider. Valid values are:
SQL (meaning, the Microsoft Native SQL Provider)
OLEDB
ODBC
ORACLE
Page 55 of 337
lr_db_dataset_action
Performs an action on a dataset.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_dataset_action
int lr_db_dataset_action("StepName=<step_name>",
"DatasetName=<dataset_name>", "Action=<action>", LAST);
Example See Also
The lr_db_dataset_action function sets the cursor to the first record of the
dataset, removes it
from memory, or prints the dataset to the Replay Log.
When printing a dataset, only the first one hundred records are listed in the test
report summaries.
The total number of records is also listed.
DatasetName Logical name for the dataset specified in lr_db_executeSQLStatement .
Action The action to perform on the dataset:
RESET: Set the cursor to the first record of the dataset.
REMOVE: Releases the memory allocated for the dataset.
PRINT: Prints the contents of the entire dataset to the Replay Log and other test
report summaries.
Page 56 of 337
lr_db_disconnect
Disconnects from a database.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_disconnect
int lr_db_disconnect("StepName=<step_name>",
"ConnectionName=<connection_name>", LAST);
Example See Also
The lr_db_disconnect function disconnects a database connection.
You must call lr_db_disconnect for each connection established by lr_db_connect to
terminate the
connection.
Add lr_db_disconnect to the vuser_end section of the script. Adding this function to
the Action
section can increase performance overhead during load testing.
ConnectionName The logical name for the connection specified in lr_db_connect .
Page 57 of 337
lr_db_executeSQLStatement
Submits an SQL statement to a database.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_executeSQLStatement
int lr_db_executeSQLStatement("StepName=<step_name>",
"ConnectionName=<connection_name>",
"SQLStatement=<statement>",
["DatasetName=<dataset_name>",] LAST);
Example See Also
The lr_db_executeSQLStatement submits an SQL statement to a database.
When SQLStatement is a SELECT statement, DatasetName points to the resulting
dataset. In this
context, the term dataset is used to describe tables of data (formatted as rows and
columns). The
data in the dataset can be manipulated by subsequent steps in the script.
When SQLStatement is either DELETE, INSERT, or UPDATE, a warning is issued to
the Replay Log and
the test results summary.
After calling this function, the row is undefined. In this case, make sure to set Row to
next or 1 if
calling lr_db_getValue after this function.
ConnectionName The logical name for the connection specified in lr_db_connect .
SQLStatement The SQL statement, such as SELECT, INSERT, DELETE, and UPDATE.
The syntax
is database-dependent. SQLStatement can be parameterized.
DatasetName Logical name for the resulting dataset from the SQL query, by which
you can refer
to the dataset in subsequent steps. For use only when SQLStatement is a SELECT
statement.
Page 58 of 337
lr_db_getValue
Retrieves a value from a dataset.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_getValue
int lr_db_getValue("StepName=<step_name>",
"DatasetName=<dataset_name>",
"Column=<column>", "Row=<row>", "OutParam=<output_parm>",
LAST);
Example See Also
The lr_db_getValue function retrieves a value from the dataset created by an
lr_db_executeSQLStatement.
When this function reaches the last row of the dataset, the row is undefined. If
Row=next is
specified the next time lr_db_getValue is called, the script continues to the first
record without
issuing any errors.
This function does not support the print or output of binary data. Binary values
retrieved from the
dataset appear as <binary_data>.
DatasetName Logical name for the dataset specified in lr_db_executeSQLStatement .
Column The name of the column in the dataset from which to retrieve the value.
Row Sets the dataset cursor to the specifed row before fetching data. One of:
The row number (1-based)
current - does not move the cursor
next - sets the cursor to the next row
OutParam The LoadRunner parameter that will contain the value.
Page 59 of 337
lr_debug_message
Sends a debug message to the log file.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_debug_message
int lr_debug_message (unsigned int message_level, const char
*format, ... );
Example See Also
Java Language
int lr.debug_message ( int message_level, String message );
Visual Basic
function lr.debug_message ( ByVal message_level as Integer, ByVal
message as string )
as Integer
The lr_debug_message function sends a debug message when the specified
message level is active.
If the specified message level is not active, a message is not issued. You can set the
active message
level to MSG_CLASS_BRIEF_LOG or MSG_CLASS_EXTENDED_LOG from the user
interface or by using
lr_set_debug_message. To determine the current level, use lr_get_debug_message.
Note that you can also specify multiple message levels with an OR separator ("|"). If
any one of the
levels are active (from the UI), the message is issued to the Output window. If none
of the levels are
active, the message is not issued.
The message is sent to the output window. To display the debug messages in the
LoadRunner output
window or Application Management agent log file, use the Expert Mode Settings.
Activate Expert Mode
(Tools > Expert Mode) and then choose Tools > Options > Debug Information
and select the
General check box.
message_level One of the Message Log Run-Time Settings. Disabled does not apply.
format A formatted string which is the message to be sent to the log file. You may
use the
standard Message Formatting that is available for printf.
Page 60 of 337
lr_decrypt
Decrypts an encoded string
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_decrypt
char *lr_decrypt (const char *EncodedString);
Example See Also
Java Language
String lr.decrypt ( String EncodedString );
Visual Basic
function lr.decrypt ( ByVal EncodedString as String ) as String
The lr_decrypt function decrypts an encoded string. This function is generated
during recording to
encode passwords. VuGen records the actual password but displays an encoded
version of the
password within the lr_decrypt function.
When you run the script, the test run component decrypts the password. Each time
you record,
VuGen encrypts the password differently, even when you use the same password.
It is possible to create an lr_decrypt call from a recorded value in the script. Select
an entire string
between quote marks, not including the quote marks themselves. Right-click in the
selected string and
choose the ENCRYPT STRING option. The original string is replaced with an lr_decrypt
call where the
EncodedString argument is the original string after encoding.
To get an encryped value from a recorded value for later use, copy the recorded
value. Then run
Start > Programs > LoadRunner > Tools > Password Encoder. Paste the value
into the Password
field, and click Generate. The encrypted string appears in the Encoded string box.
Click the Copy
button, then paste the encryped string into a parameter for later use, or assign the
value to a string
variable.
VuGen uses 32 bit encryption.
EncodedString The encoded string you want to decrypt.
Page 61 of 337
lr_disable_ip_spoofing
Disables IP Spoofing
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_disable_ip_spoofing
int lr_disable_ip_spoofing ( );
Example See Also
lr_disable_ip_spoofing disables IP spoofing during a script run.
Page 62 of 337
lr.empty
Returns an Variant whose value is Empty.
Java Script
HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr.) > lr.empty
Variant lr.empty ();
Example See Also
VB Script
Function lr.empty () as Variant;
Example See Also
Use lr.empty to pass an Empty variant to a function that requires a Variant
argument.
In Visual Basic, VB.NET or C#, use the class or keyword Empty.
Page 63 of 337
lr_enable_ip_spoofing
Enables IP Spoofing
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_enable_ip_spoofing
int lr_enable_ip_spoofing ( );
Example See Also
lr_enable_ip_spoofing enables IP spoofing during a script run.
Page 64 of 337
lr_end_sub_transaction
Marks the end of a sub-transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_sub_transaction
int lr_end_sub_transaction (const char *sub_transaction, int status );
Example See Also
Java Language
int lr.end_sub_transaction ( String sub_transaction, int status );
Visual Basic
function lr.end_sub_transaction ( sub_transaction as String, status as
Integer ) as
Integer
The lr_end_sub_transaction function marks the end of a sub-transaction. To mark
the beginning of
the sub-transaction, use the lr_start_sub_transaction function. You insert these
functions immediately
before and after the sub-transaction steps.
Multiple sub-transactions can be nested within a parent transaction, but each
lr_end_sub_transaction statement must match an lr_start_sub_transaction
statement or it will be
interpreted as an illegal command.
sub_transaction A string indicating the name of an existing sub-transaction.
status The transaction status.
Page 65 of 337
lr_end_timer
Stops a timer.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_timer
Example Return Values Parameterization See Also
double lr_end_timer (merc_timer_handle_t timer);
Example See_Also
lr_end_timer stops a timer that began timing when lr_start_timer was called. It
returns the elapsed
time in seconds. The resolution depends on the run-time environment. The
maximum resolution is a
microsecond.
timer The handle of the timer returned by lr_start_timer.
Page 66 of 337
lr_end_transaction
Marks the end of a transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_transaction
int lr_end_transaction (const char *transaction_name, int status ) ;
Example See Also
Java Language
int lr.end_transaction ( String transaction_name, int status );
Visual Basic
function lr.end_transaction ( ByVal transaction_name as string, ByVal
status as Integer )
as Integer
The lr_end_transaction function marks the end of a transaction and records the
amount of time it
took to perform the transaction. To indicate a transaction to be analyzed, place the
lr_start_transaction function before the transaction, and the lr_end_transaction
function after the
transaction.
You can manually set the status of the transaction or you can allow the script to
detect it
automatically. To manually set the status, you perform a manual check within the
code of your script
(see example) evaluating the return code of a function. For the "succeed" return
code, set the status
to LR_PASS. For a "fail" return code, set the status to LR_FAIL. For an "aborted"
return code, set the
status to LR_STOP.
If status is LR_AUTO, then the value of status is automatically assigned. By default,
this value is
LR_PASS signifying a successful transaction. However, if prior to
lr_end_transaction, you change the
default value using lr_set_transaction_status,
lr_set_transaction_status_by_name,
lr_set_transaction_instance_status or lr_fail_trans_with_error, then this is
the value which is
passed as status in lr_end_transaction.
If you make a series of calls to functions that modify the LR_AUTO status, then it is
the last call
before lr_end_transaction which effectively changes the status.
transaction_name A string indicating the name of an existing transaction.
status The Transaction Status
Page 67 of 337
lr_end_transaction_instance
Marks the end of a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_transaction_instance
int lr_end_transaction_instance (long parent_handle, int status );
Example See Also
The lr_end_transaction_instance function marks the end of a transaction instance
and records the
amount of time it took to perform the transaction. To indicate a transaction instance
to be analyzed,
place the lr_start_transaction_instance function before the transaction, and the
lr_end_transaction_instance function after the transaction.
You can manually set the status of the transaction instance or you can allow the
script to detect it
automatically. To manually set the status, you perform a manual check within the
code of your script
(see example) evaluating the return code of a function. For the "succeed" return
code, set the
transaction status to LR_PASS. For a "fail" return code, set the status to LR_FAIL.
For an "aborted"
return code, set the status to LR_STOP.
To instruct the script to automatically detect the status, specify LR_AUTO. The script
returns the
detected.
parent_handle The handle returned by lr_start_transaction_instance at the creation
of the
instance.
status The transaction status.
Page 68 of 337
lr_error_message
Sends an error message with location details to the output windows, log files, and
other test report
summaries.
int lr_error_message (const char *format, exp1, exp2,...expn. );
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_error_message
Example See Also
Java Language
int lr.error_message ( String message );
Visual Basic
function lr.error_message ( ByVal message as String ) as Integer
The lr_error_message function sends an error message to product output windows
(such as the
LoadRunner output window), log files (such as Vugen and the Application
Management agent log file),
and other test report summaries. For details regarding the output for each product,
see the products'
user guides.
To send a special notification that is not specifically an error message, use
lr_output_message.
If Run-time settings > General > Miscellaneous > Fail open transactions on
lr_error_message
is selected, calling lr_error_message will fail the transaction in addition to sending
the message. If
you want to save the elapsed time in spite of the transaction failure, capture the
time with
lr_get_transaction_duration before calling lr_error_message, then create a
transaction to report the
time with lr_set_transaction.
It is not recommended that you send a message to the Output window in the middle
of a transaction,
as it will lengthen the execution time. Instead, use lr_log_message to send the
message only to the
Vuser log file. This conserves the resources required for sending messages to the
VuGen displays the message text of the lr_error_message function in the
Execution log in red, using
Error code 17999. Note that this function sends a message to the output even when
logging is
disabled in the run-time settings.
In the Vuser Execution log, this function lists the location and line number from
where the message
was issued. To issue a message without those details, use lr_message.
Out put of l r _er r or _message( " out put message" ) ; - Act i on( 4) : out put
message
Out put of l r _message( "message" ) ; -
message
format
C Language
A formatted string to send to the Output window. You may specify a literal string in
quotation marks or use the standard Message Formatting that is available for printf.
exp
1
, exp
2
,..
exp
n
C Language
The expressions or variables to be formatted.
message
Java and
Visual Basic
A string containing the error message to send to the Output window. See VB String
Arguments and Java String Arguments.
Page 69 of 337
Page 70 of 337
lr.eval_double
Returns the double value of the parameter.
Visual Basic and VB Script
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.eval_double
function lr.eval_double (ByVal param_name as String ) as Double
The lr.eval_double function returns the value of the parameter as a double
param_name The parameter to evaluate.
Page 71 of 337
lr.eval_long
Returns the long value of the parameter.
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.eval_long
function lr.eval_long (ByVal param_name as String ) as long
The lr.eval_long function returns the value of the parameter as a Long.
param_name The parameter to evaluate.
Page 72 of 337
lr_eval_string
Returns the string argument after evaluating embedded parameters.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string
char *lr_eval_string (const char *instring );
Example See Also
Java Language
String lr.eval_string ( String instring );
Visual Basic
function lr.eval_string (ByVal instring as String ) as String
The lr_eval_string function returns the input string after evaluating any embedded
parameters. If the
string argument contains only a parameter, the function returns the current value of
the parameter.
Embedded parameters must be in brackets.
Note: lr_eval_string allocates memory internally. The memory is freed at the end
of each iteration. If
you evaluate a parameter or parameters in a loop, conserve memory by not using
lr_eval_string .
Instead, use lr_eval_string_ext and free the memory in each loop iteration with
lr_eval_string_ext_free.
instring The string to evaluate.
Page 73 of 337
lr_eval_string_ext
Creates a buffer and assigns it the input string after evaluating embedded
parameters.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string_ext
int lr_eval_string_ext (const char *in_string, unsigned long const
in_len, char ** const
out_str, unsigned long * const out_len, unsigned long const options,
const char *file,
long const line );
Example See Also
The lr_eval_string_ext function evaluates in_str by replacing parameters with their
string value. It
creates a buffer containing the expanded string and sets out_str to point to that
buffer. It also
assigns the length of the buffer to out_len.
Note that in_len is the length of the argument you pass, and not the length of the
value of the
parameter. For example, if parameter ABC contains the string "1234567890", the
call is:
l r _eval _s t r i ng_ext ( "{ABC}" , 5
After using lr_eval_string_ext, free the memory allocated for the output buffer
with
lr_eval_string_ext_free.
This function is useful when correlating statements that use binary data, for
example, data with
embedded NULL characters.
Use this function in conjunction with lr_eval_string_ext_free in preference to
lr_eval_string when
evaluating strings in a loop. Using lr_eval_string in a loop uses more memory.
in_str The string to be evaluated.
in_len The length of the name of argument in_str +2 to account for the parentheses.
out_str A pointer to the output buffer.
out_len The length of the output buffer.
options Reserved for future use. Currently set to "0".
file Reserved for future use. Currently set to "0".
line Reserved for future use. Currently set to "-1".
Page 74 of 337
lr_eval_string_ext_free
Frees the buffer allocated by lr_eval_string_ext.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string_ext_free
void lr_eval_string_ext_free (const char **param);
Example See Also
The lr_eval_string_ext_free function frees the memory allocated by
lr_eval_string_ext .
param A pointer to the buffer.
Page 75 of 337
lr_exit
Exits from the script, action, or iteration.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_exit
void lr_exit (int continuation_option, int exit_status);
Example See Also
Java Language
void lr.exit (int continuation_option, int exit_status);
The lr_exit function allows you to exit from the script run during execution.
A transaction in which lr_exit is called does not appear in the LoadRunner controller
in the
Transaction Status box. It is ignored in the count of passed and failed transactions.
If lr_exit is called several times in the same script, whether in different actions or
different iterations,
it is the exit status of the last call that determines the status of the Vuser group
running the script.
The controller's Scenario Groups Status box displays the status. It is the column in
which the group
appears after the run stops.
continuation_option The continuation option specifies how the script continues after
the call to
lr_exit
exit_status The status of the scenario group as a result of calling lr_exit
Page 76 of 337
lr_fail_trans_with_error
Sets the default status of open transactions to LR_FAIL and sends an error message.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_fail_trans_with_error
Example Return Values Parameterization See Also
int lr_fail_trans_with_error (const char *format, exp1,
exp2,...expn.);
The lr_fail_trans_with_error function sets the default exit status to LR_FAIL for all
open
transactions with LR_AUTO in their lr_end_transaction statement and sends an error
message.
The message is sent to the LoadRunner output window or Application Management
agent log file.
A transaction's final status is defined in the status parameter of the
lr_end_transaction statement. If
this status is LR_AUTO, then the value is automatically assigned. By default the
value assigned is
LR_PASS, which signifies a successful transaction. lr_fail_trans_with_error
changes this default
value to LR_FAIL.
Use the format and exp parameters in the same way as the standard Message
Formatting that is
available for printf. If it is a literal string, enclose it with quotation marks.
format A string describing the format to use to write the optional remaining
expressions exp
1
,
exp
2
,.. exp
n
. You may specify a literal string in quotation marks or use the standard
Message Formatting that is available for printf.
exp
1
,
exp
2
,..
exp
n
The optional expressions (variables) to be formatted and printed.
Page 77 of 337
lr_get_attrib_double
Returns a value of the calling mdrv command's parameter as a double.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_double
double lr_get_attrib_double (const char *parameter);
Example See Also
Java Language
double lr.get_attrib_double ( String parameter );
Example See Also
Visual Basic
function lr.get_attrib_double ( ByVal parameter as String ) as double
The lr_get_attrib_double function returns the value of a command line parameter
whose type is a
double precision floating point when the script is run using the mdrv command. You
place the
command line parameter's name in the function's argument field and
lr_get_attrib_double returns the
value of that parameter.
The function returns NULL if the mdrv command line was not used to run the script
(for example, the
script was run directly in VuGen or by LoadRunner). For more information on the
running scripts using
the mdrv command line, see the HP LoadRunner Virtual User Generator User Guide.
The Command Line Parsing Functions functions eliminate the need to parse the
command line manually.
parameter The name of a parameter which can be interpreted as a double value.
Page 78 of 337
lr_get_attrib_long
Returns a value of the calling mdrv command's parameter as a long integer.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_long
long lr_get_attrib_long (const char *parameter);
Example See Also
Java Language
long lr.get_attrib_long ( String parameter );
Visual Basic
function lr.get_attrib_long ( ByVal parameter as String ) as long
The lr_get_attrib_long function returns the value of a command line parameter
whose type is long
integer when the script is run using the mdrv command. You place the command line
parameter name
in the function's argument field and lr_get_attrib_long returns the value of that
parameter.
(for example, the
parameter The name of a parameter which can be interpreted as a double value.
Page 79 of 337
lr_get_attrib_string
Returns a value of the calling mdrv command's parameter as a string.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_string
char *lr_get_attrib_string (const char *argument);
Example See Also
Java Language
String lr.get_attrib_string ( String parameter );
Visual Basic
function lr.get_attrib_string ( ByVal parameter as String ) as String
The lr_get_attrib_string function returns a command line argument string when
the script is run
using the mdrv command. You place the argument name in the function's argument
field and
lr_get_attrib_string returns the string values associated with that argument.
(for example, the
The function returns NULL if the argument you specify is invalid. This is useful for
checking if a
command line option or a specific value is valid.
argument A command line argument whose value is a string.
Page 80 of 337
lr_get_debug_message
Returns the current message logging settings.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_debug_message
unsigned int lr_get_debug_message ( );
Example See Also
Java Language
int lr.get_debug_message ( );
Visual Basic
function lr.get_debug_message ( ) as Integer
The lr_get_debug_message function returns the current log run-time settings .
The settings
determine what information is sent output. The log settings are specified with the
run-time settings
dialog, or by using the lr_set_debug_message function.
The debug messages are sent to the LoadRunner output window or Application
Management agent log
file.
To evaluate the returned value, you can perform a bitwise AND operation. This
allows you to
determine which options are set. See the C syntax example.
Page 81 of 337
lr_get_host_name
Returns the name of the host.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_host_name
char *lr_get_host_name ( );
Example See Also
Java Language
String lr.get_host_name ( );
Visual Basic
function lr.get_host_name ( ) as String
The lr_get_host_name function returns the name of the machine executing the
script.
Page 82 of 337
lr_get_master_host_name
Returns the name of the Controller host.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_master_host_name
char *lr_get_master_host_name ( );
Example See Also
Java Language
String lr.get_master_host_name ( );
Visual Basic
function lr.get_master_host_name ( ) as String
The lr_get_master_host_name function returns the name of the machine running
the Controller .
Not applicable for products that do not run Vusers.
Page 83 of 337
lr_get_transaction_duration
Returns the duration of a transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_duration
double lr_get_transaction_duration (const char *transaction);
Example See Also
Visual Basic
function lr.get_transaction_duration ( String transaction ) as double
The lr_get_transaction_duration function returns the duration in seconds of the
specified
transaction to this point. You use this function to determine the total transaction
time before the
transaction has ended. lr_get_transaction_duration returns values greater than
zero only for open
transactions.
This function returns the duration including Wasted Time. Therefore, the value may
be slightly greater
than the duration reported for the function when closed with lr_end_transaction.
To determine other transaction statistics, such as think time and wasted time, use
the Transaction
Functions.
transaction A string indicating the name of a transaction.
Page 84 of 337
lr_get_transaction_status
Returns the current status of a transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_status
int lr_get_transaction_status ( const char *transaction_name ) ;
Example See Also
lr_get_transaction_status returns the current status of a transaction.
lr_get_transaction_status
cannot be invoked after lr_end_transaction. Since lr_get_transaction_status can
only return the
status of an open transaction, it cannot report the final transaction status.
This function can be useful when a transaction, which is made up of a number of
steps, can fail at
various points. By checking the status and terminating the Vuser, you can prevent
unnecessary
activity.
transaction_name The name of the transaction.
Page 85 of 337
lr_get_transaction_think_time
Returns the think time of a transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_think_time
double lr_get_transaction_think_time (const char *transaction);
Example See Also
Visual Basic
function lr.get_transaction_think_time ( String transaction ) as
double
The lr_get_transaction_think_time function returns the think time of the
specified transaction until
this point. It returns values greater than zero only for open transactions.
the appropriate
Transaction Functions.
transaction The transaction name .
Page 86 of 337
lr_get_transaction_wasted_time
Returns the wasted time of a transaction by its name.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_wasted_time
double lr_get_transaction_wasted_time (const char *transaction);
Example See Also
The lr_get_transaction_wasted_time function returns the Wasted Time in
seconds of the specified
transaction to this point.
The lr_get_transaction_wasted_time function returns values greater than zero
only for open
transactions.
the appropriate
transaction The name of the transaction.
Page 87 of 337
lr_get_trans_instance_duration
Returns the duration of a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_duration
double lr_get_trans_instance_duration (long trans_handle);
Example See Also
The lr_get_trans_instance_duration function returns the duration of an open
transaction instance
in seconds until this point. Use this function to determine the total transaction time
before the
transaction has ended.
The difference between this function and lr_get_transaction_duration is that here
you specify a
transaction instance by its handle. With lr_get_transaction_duration, you specify
an independent
transaction by its name.
The trans_handle is the return value of a call to lr_start_transaction_instance .
lr_get_trans_instance_duration returns values greater than zero only for open
transactions.
the appropriate
trans_handle A transaction handle.
Page 88 of 337
lr_get_trans_instance_status
Returns the current status of a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_status
int lr_get_trans_instance_status ( long transaction_handle ) ;
Example See Also
lr_get_trans_instance_status returns the current status of a transaction instance.
lr_get_trans_instance_status cannot be invoked after
lr_end_transaction_instance . It cannot
report the final transaction instance status.
The transaction_handle is the handle returned by the call to
lr_start_transaction_instance that
created the instance.
This function can be useful when a transaction instance, which is made up of a
number of steps, can
fail at various points of its execution. By checking the status and terminating the
Vuser, you can
prevent unnecessary activity.
transaction_handle The name of the transaction.
Page 89 of 337
lr_get_trans_instance_think_time
Returns the think time of a transaction instance specified by its handle.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_think_time
double lr_get_trans_instance_think_time (long trans_handle);
Example See Also
The lr_get_trans_instance_think_time function returns the think time of the
specified transaction
until this point.
The difference between this function and lr_get_transaction_think_time is that
here you specify a
transaction instance by its handle. With lr_get_transaction_think_time, you
specify an independent
transaction by its name.
The trans_handle is the handle returned by the call to lr_start_transaction_instance
that created the
instance.
The lr_get_trans_instance_think_time function returns values greater than zero
only for open
transactions.
the appropriate
Page 90 of 337
lr_get_trans_instance_wasted_time
Returns the wasted time of a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_wasted_time
double lr_get_trans_instance_wasted_time (long trans_handle);
Example See Also
The lr_get_trans_instance_wasted_time function returns the Wasted Time of the
specified
transaction until this point.
The difference between this function and lr_get_transaction_wasted_time is that
here you specify
a transaction instance by its handle. With lr_get_transaction_wasted_time, you
specify an
independent transaction by its name.
The trans_handle is the handle returned by the call to lr_start_transaction_instance
that created the
instance.
The lr_get_trans_instance_think_time function returns values greater than zero
only for open
transactions.
the appropriate
Page 91 of 337
lr_get_vuser_ip
Returns the IP address of a Vuser.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_vuser_ip
char *lr_get_vuser_ip( );
Example See Also
Visual Basic
function lr.get_vuser_ip() as String
The lr_get_vuser_ip function returns the IP address of a Vuser. When performing
IP spoofing, each
Vuser can use a different address. This function allows you to determine the current
Vuser's IP
address.
If the IP was set with the web_set_sockets_option function using the
IP_ADDRESS_BY_INDEX
option, lr_get_vuser_ip returns that IP.
Page 92 of 337
lr_load_dll
Loads an external DLL.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_load_dll
int lr_load_dll (const char *library_name );
Example See Also
The lr_load_dll function loads a DLL (Windows) or shared object (UNIX) allowing
you to call an
external function when replaying using the C interpreter. Once you load the DLL, you
can call any
function defined in the DLL, without having to declare it.
You can specify a full path for the DLL.
On Windows platforms, if you do not specify a path, lr_load_library searches for the
DLL using the
standard sequence used by the C++ function, LoadLibrary .
On UNIX platforms, you can set the LD_LIBRARY_PATH environment variable (or the
platform
equivalent). The lr_load_dll function uses the same search rules as dlopen. For
more information, see
the man pages for dlopen or its equivalent.
library_name The name of a DLL (Windows) or shared object (UNIX).
Page 93 of 337
lr_log_message
Sends a message to the Application Management agent log file or the LoadRunner
Vuser log.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_log_message
int lr_log_message (const char *format, exp1, exp2,...expn.);
Example See Also
Java Language
int lr.log_message ( String message );
Visual Basic
function lr.log_message ( ByVal message as String ) as Integer
The lr_log_message function sends a message to the Vuser or agent log file
(depending on the
application), and not to the output window. You can use this function for debugging
by sending error
or other informational messages to the log file.
You can avoid overloading the network by using this function to send messages to
the log file rather
than sending messages to the Output window (with lr_error_message or
lr_output_message). In a
standalone program such as VuGen, lr_log_message sends the message to the
viewer and
output.txt.
To send a message to the output file, you must enable logging in the run-time
settings, and select
Always send messages. If you select Send messages only when an error
occurs, there is no
output from this function.
In the Vuser Execution log, this function does not list the location and line number
from where the
message was issued. To issue a message with those details, use lr_output_message.
format
C Language
A formatted string to send to the log file. If it is a literal string, enclose it with
quotation marks. Use the standard Message Formatting that is available for printf
to set the format for the expressions you want to print.
exp1, exp2,..
expn
C Language
The expressions (variables) to be formatted and printed.
message
Object oriented
languages
A string containing the message to send to the log.
See VB String Arguments and Java String Arguments.
statement Output
lr_log_message("a message") a message
lr_output_message("message"); Action(4): a message
Page 94 of 337
lr_message
Sends a message to the log and output window.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_message
int lr_message (const char *format, exp1, exp2,...expn.);
Example See Also
Java Language
int lr.message ( String message );
Visual Basic
function lr.message ( ByVal message as String ) as Integer
The lr_message function sends a message to the log file and output window. When
run in VuGen, the
output file is output.txt.
Use lr_log_message instead of this function to send the message only to the log file.
This conserves
the network and controller resources required for sending messages to the output.
occurs, there is no
In the log file, this function does not list the location and line number from where the
message was
issued. To issue a message with those details, use lr_output_message.
format
C Language
A formatted string. If it is a literal string, enclose it with quotation marks. Use the
standard Message Formatting that are available for printf to set the format for the
expressions you want to print.
exp
1
, exp
2
,..
exp
n
C Language
message
Object
oriented
A string containing the message to send to the Output window.
statement Output
lr_message("a message") a message
lr_output_message("a message"); Action(4): a message
Page 95 of 337
lr.missing
Returns an Variant whose value is Missing.
Java Script
HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr.) > lr.missing
Variant lr.missing ();
Example See Also
VB Script
Function lr.missing () as Variant;
Example See Also
Use lr.empty to pass an Missing variant to a function that requires a Variant
argument.
In Visual Basic, VB.NET or C#, use the class or keyword MISSING.
Page 96 of 337
lr_output_message
Sends a message to log files, output windows, and other test report summaries.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_output_message
int lr_output_message (const char *format, exp1, exp2,...expn.);
Example See Also
Java Language
int lr.output_message ( String message );
Visual Basic
function lr.output_message ( ByVal message as String ) as Integer
The lr_output_message function sends a message with the script section and line
number to output
windows (such as the LoadRunner output window), log files (such as the Vugen log
file and the
Application Management Web site and agent log file), and other test report
summaries.
For details regarding the output for each product, see the products' user guides.
When a script is run in VuGen, the output file is output.txt.
To send an error message to the LoadRunner output window or Application
Management agent log, use
the lr_error_message function. It is not recommended that you send a message to
the output window
or agent log in the middle of a transaction, as it will lengthen the execution time. To
send a message
to the Vuser execution log or Application Management Web site, but not to the
Output window, use
lr_log_message.
occurs, there is no
To issue a message without including the location details, use lr_message.
format
C Language
A formatted string. If it is a literal string, enclose it with quotation marks. Use the
standard Message Formatting that is available for printf to set the format for the
expressions you want to print.
exp
1
, exp
2
,..
exp
n
C Language
message
Object
Oriented
A string containing the message to send to the Output window.
statement Output
lr.log_message("a message") a message
lr.output_message("a message"); Actions.java (4): a message
Page 97 of 337
Note: Do not send null pointers as arguments to string formats e.g.

char *str = NULL;
lr_output_message("%s", str);
Page 98 of 337
lr_paramarr_idx
Returns the value of the parameter at a specified location in a parameter array.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_paramarr_idx
char * lr_paramarr_idx ( const char * paramArrayName, unsigned int
index);
Example See Also
lr_paramarr_idx returns a string containing the value of the parameter at the
specified position in a
parameter array. If the parameter does not exist, the return value is the
concatenation of "{",
paramArrayName, "_", index, and "}", for example, "{myParam_4}".
paramArrayName The name of the parameter array from which to return the value.
index The one-based position of the parameter in the array.
Page 99 of 337
lr_paramarr_len
Returns the number of elements in a parameter array.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_paramarr_len
int lr_paramarr_len (const char * paramArrayName);
Example See Also
lr_paramarr_len returns the number of elements in a parameter array.
paramArrayName The name of the parameter array.
Page 100 of 337
lr_paramarr_random
Returns the value of the parameter at a random location in a parameter array
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_paramarr_random
char * lr_paramarr_random (const char * paramArrayName);
Example See Also
lr_paramarr_random returns a string containing the value of the parameter in a
parameter array.
The value is returned from the parameter at a position chosen randomly by
LoadRunner.
paramArrayName The name of the parameter array.
Page 101 of 337
lr_param_increment
Increments the value of a numerical parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_increment
int lr_param_increment (const char *destination_param, const char
*source_param);
Example See Also
The lr_param_increment function retrieves the value of source_param, increments
its value by one,
and stores the incremented value as a null terminated string in destination_param.
This function is useful only in protocols that have a numerical parameter type. For
protocols that have
only string parameters, increment with C functions. For example:
i = at oi ( l r _eval _st r i ng( "{modi f i cat i on_num}" ) ) ;
spr i nt f ( buf , "%d" , i +1) ;
l r _save_st r i ng( buf , "next _modnum" ) ;
For protocols that have a numerical parameter, lr_param_increment can be used:
l r _par am_i nc r ement ( "next _modnum" , "{modi f i cat i on_num}" ) ;
source_param must be initialized with an integer value prior to calling
lr_param_increment.
source_param's value should include only single-byte digit characters with an
optional sign or leading
zeros.
When destination_param exists, its value is overwritten. When it doesn't exist, the
parameter is
created dynamically.
The value of source_param is restricted to the maximum value of a long integer
minus 1.
destination_param The name of the parameter to store the incremented parameter
source_param The name of the parameter whose value is incremented
Page 102 of 337
lr_param_sprintf
Writes formatted output to a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_sprintf
int lr_param_sprintf ( const char * paramName, const char * format
[,args ... ] );
Example See Also
lr_param_sprintf functions like the standard C function sprintf except that the
formatted string is
written to a LoadRunner parameter instead of a string buffer.
These formatting characters are not supported: %E, %hd, %hhd, %lld, %ld, %hhi,
%lli, %hhu , %llu,
%hhf , %llf, %hhe, and %lle.
paramName The target parameter to which the string is written.
format One or more formatting characters.
args Optional print arguments.
Page 103 of 337
lr_param_unique
Generates a unique string and assigns it to a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_unique
int lr_param_unique (const char * paramName);
Example See Also
lr_param_unique generates a string of format:
<GroupName><UserID><CurrentTime>. The string contains no spaces.
paramName The target parameter to which the string is written.
Page 104 of 337
lr_peek_events
Checks for events.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_peek_events
void lr_peek_events ( );
Example See Also
Java Language
void lr.peek_events ( );
Visual Basic
sub lr.peek_events ( )
The lr_peek_events function suspends the Vuser script run and checks for events
before resuming.
Scripts written in C language perform this check internally. Therefore, there is no
need to use the
lr_peek_events function.
Scripts written in Java or Visual Basic do not perform this check internally.
Therefore, insert this
function into your Vuser script at the point at which you want the Vuser to pause.
Page 105 of 337
lr.read_xml
Returns the contents of an XML file as a string.
Your cannot use standard parameterization with this function.
Java and Java Script
HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr.) > lr.read_xml
String.lr.read_xml (String file_name);
Example See Also
The lr.read_xml function returns the contents of the specified file as a String. If the
call fails, it
returns null.
file_name The file to read and return as a string. The file must exist in the
data\SerializedObjects
directory under the script directory.
Page 106 of 337
lr_rendezvous
Creates a rendezvous point in the Vuser script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_rendezvous
int lr_rendezvous (const char *rendezvous_name);
Example See Also
Java Language
int lr.rendezvous ( String rendezvous_name );
Visual Basic
function lr.rendezvous ( ByVal rendezvous_name as String ) as Integer
The lr_rendezvous function creates a rendezvous point in a Vuser script. When this
statement is
executed, the Vuser program stops and waits for permission from LoadRunner to
continue.
This function can only be used in action section, and not in vuser_init or vuser_end.
The difference between lr_rendezvous and lr_rendezvous_ex is that
lr_rendezvous always
returns zero.
rendezvous_name The name of the rendezvous.
Page 107 of 337
lr_rendezvous_ex
Creates a rendezvous point in the Vuser script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_rendezvous_ex
int lr_rendezvous_ex (const char *rendezvous_name);
Example See Also
The lr_rendezvous_ex function creates a rendezvous point in a Vuser script. When
this statement is
executed, the Vusers stop and wait for permission from LoadRunner to continue.
The default timeout is 30 sec. The timeout is set in the scenario policy in the
Controller.
This function can only be used in an action section, and not in vuser_init or
vuser_end.
The difference between this function and lr_rendezvous is that lr_rendezvous
returns only LR_PASS
or LR_FAIL.
rendezvous_name The name of the rendezvous.
Page 108 of 337
Rendezvous Return Values

The return values of the lr_rendezvous function are defined in the Lrun.h file. On
PC platforms, the
function returns one of the values described in the table. On UNIX platforms, the
function returns 0 for
success and -1 for an illegal name:
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Rendezvous Return Values
Return Code Name Code Meaning
LR_REND_ALL_ARRIVED 0 Vuser was released after all the designated Vusers
arrived.
LR_REND_TIMEOUT 1 Vuser was released after the timeout value was reached.
LR_REND_DISABLED 2 The rendezvous was disabled from the Controller.
LR_REND_NOT_FOUND 3 The rendezvous was not found.
LR_REND_VUSER_NOT_
MEMBER
4 Vuser was not defined in the rendezvous.
LR_REND_VUSER_DISABLED 5 Vuser was disabled for the rendezvous.
LR_REND_BY_USER 6 The rendezvous was released by the user.
Page 109 of 337
lr_resume_transaction
Resumes reporting transaction data within a script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_resume_transaction
void lr_resume_transaction (const char *transaction_name);
Example See Also
Visual Basic
Sub lr.resume_transaction ( String transaction_name )
This function is retained for backward compatibility. For more general ways of
reporting partial
transaction durations, see lr_start_sub_transaction, and lr_set_transaction.
The lr_resume_transaction function resumes the reporting of transaction data
within the script that
was suspended by lr_stop_transaction. After a call to lr_stop_transaction,
statistics returned by the
"get" Transaction Functions reflect only the data up to that call, until this function is
called.
Data collection, however, is not interrupted. After the call to
lr_resume_transaction, the "get"
functions return all data since the start of the transaction. Furthermore, the final
results when the
test is analyzed will reflect the total values, including the periods in between the
transaction stop and
resume.
If lr_resume_transaction is not called, the "get" functions and the final results
reflect only the
duration from the transaction start to the lr_stop_transaction call. Thus,
lr_stop_transaction and
lr_resume_transaction can be used conditionally to collect information either
about an entire
transaction, or only the beginning. To accomplish this, call lr_resume_transaction
only if your
condition is met.
Note: When data is collected this way, the data in analysis will reflect both the tests
where the
condition for lr_resume_transaction is met, and the tests where it is not.
If the section you may wish to exclude ends before the end of the transaction, this
technique does
not apply. If you need to differentiate between occurrences where the
condition is met and those where it is not in the analysis data, this technique does
not apply.
For other ways of recording durations conditionally, see lr_start_sub_transaction,
and
lr_set_transaction.
Page 110 of 337
lr_resume_transaction_instance
Resumes reporting transaction instance data within a script
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_resume_transaction_instance
void lr_resume_transaction_instance ( long trans_handle );
Example See Also
The lr_resume_transaction_instance function resumes the reporting of
transaction data within the
script that was suspended by lr_stop_transaction_instance. After a call to
lr_stop_transaction_instance, statistics returned by the "get" Transaction
Functions reflect only
the data up to that call, until this function is called.
lr_resume_transaction_instance, the
"get" functions return all data since the start of the transaction. Furthermore, the
final results when
the test is analyzed will reflect the total values, including the periods in between the
transaction
instance stop and resume.
If lr_resume_transaction_instance is not called, the final results reflect the
statistics only until the
call to lr_stop_transaction_instance.
The parent_handle is the value returned from the call to
lr_start_transaction_instance that created
the instance.
lr_stop_transaction_instance and lr_resume_transaction_instance can be
used to conditionally
collect information about either the beginning, or all of the transaction.
Note that you will not be able to differentiate in analysis between iterations when
lr_stop_transaction_instance was called and iterations where it was not.
For more flexible ways recording transaction times conditionally, see
lr_start_sub_transaction,
lr_set_transaction,and lr_start_timer
trans_handle The transaction instance id that was returned by
lr_start_transaction_instance
Page 111 of 337
lr_save_datetime
Assigns the current date and time to a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_datetime
void lr_save_datetime(const char *format, int offset, const char
*name);
Example See Also
The lr_save_datetime function saves the current date and time, or the date and
time with the
specified offset into a parameter. The resulting string will be truncated once it
reaches
MAX_DATETIME_LEN characters.
The format can be a format defined in an included header file, such as DATE_FM,
which is defined in
lrun.h. You can use theDatetime Format Codes to build a format with any
combination of strings and
codes. For example, depending on the definitions in your computer's locale, "The
current month is %b"
would return The current month is JAN. "%d%b%y" would return 29JAN97.
format The format of the retrieved date/time information.
offset Offset from the current date and time, using the constants: DATE_NOW,
TIME_NOW,
ONE_DAY, ONE_HOUR, ONE_MIN. For example, TIME_NOW + ONE_HOUR
name The name of the parameter to store the date/time information.
Page 112 of 337
lr.save_double
Saves a double value as a parameter.
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.save_double
Sub lr.save_double (ByVal param_name as String, value as Double )
The lr.save_double function saves value to parameter param_name. It creates the
parameter if it
does not exist.
param_name The parameter in which to save the value
value A numeric value
Page 113 of 337
lr_save_int
.
Saves an integer to a parameter.

C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_int
int lr_save_int ( int value, const char *param_name);
Example See Also
The lr_save_int function converts an integer to a string and saves the string in a
parameter. If the
parameter does not exist, it is created.
value The integer value to assign to the parameter.
param_name The name of the parameter.
Page 114 of 337
lr.save_long
Saves a long value as a parameter.
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.save_long
Sub lr.save_long (ByVal param_name as String, value as long )
The lr.save_long function saves value to parameter param_name. It creates the
parameter if it does
not exist.
param_name The parameter in which to save the value
value An integer or long integer value
Page 115 of 337
lr_save_searched_string
Searches for an occurrence of a string in a buffer and saves a portion of the buffer
after that string to
a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_searched_string
int lr_save_searched_string (const char *buffer, long buf_size,
unsigned int occurrence,
const char *search_string, int offset, unsigned int string_len, const char
*parm_name );
Example See Also
The lr_save_searched_string function searches for string search_string inside
string or character
array buffer, and finds the nth occurrence of search_string, where n is occurrence
plus 1. The substring
to be saved starts at offset after the end of the nth occurrence of search_string, and
has
length string_len.
For example:
char cBuf f [ ] = " abc Emma Woodhouse abc El i zabet h Bennet abc Wi l l i am Pr i
ce" ;
l r _s ave_s ear c hed_s t r i ng( cBuf f , st r l en( cBuf f ) ,
2, " abc" , / / Sear ch f or t hi r d occur r ence of " abc"
1, / / Ski p t he space af t er " abc"
4, / / Put t he next f our char act er s. . .
" Fannys_br ot her " ) ; / / . . . i n par amet er Fannys_br ot her .
Af t er t he cal l , t he cont ent of par amet er Fannys_br ot her i s "Wi l l " .
The search_string cannot contain null characters, but the buffer can contain null
characters.
Use the lr_save_string function to save strings from character arrays. Use
lr_save_searched_string
only when you need to save a portion of a character array relative to a string
occurrence.
buffer The STRING or CARRAY buffer, part of whose contents you want to save.
buf_size The buffer size.
occurrence The occurrence number of the search_string (0-based count). For
example, if the
search_string occurs three times, and you want the second occurrence, set
occurrence to 1.
search_string The string to search for in the buffer.
offset The number of characters to skip after the end of the search string occurrence.
string_len The number of characters to save.
parm_name Parameter name to be used in subsequent lr statements to refer to the
saved
information. Name is enclosed in double-quotes.
Page 116 of 337
lr_save_string
Saves a null-terminated string to a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_string
int lr_save_string (const char *param_value, const char
*param_name);
Example See Also
Java Language
int lr.save_string ( String param_value , String param_name);
Visual Basic
function lr.save_string ( ByVal param_name as String, ByVal
param_value as String ) as
Integer
The lr_save_string function assigns the specified null-terminated string to a
parameter. This function
is useful in correlating queries. To determine the value of the parameter, use the
lr_eval_string
function.
param_value The value to assign to the parameter.
Page 117 of 337
lr_save_var
Saves a variable length string to a parameter.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_var
int lr_save_var (const char *param_value, unsigned long const
value_len, unsigned long
const options, const char *param_name);
Example See Also
The lr_save_var function assigns the specified variable length string to a
parameter. This function is
useful in correlating queries. To determine the value of the parameter, use the
lr_eval_string function.
param_value The value to assign to a parameter.
value_len The length of the value in bytes.
options A parameter option, currently 0.
Page 118 of 337
lr_set_debug_message
Sets the message level for the script execution.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_debug_message
int lr_set_debug_message (unsigned int message_level, unsigned int
on_off);
Example See Also
Java Language
int lr.set_debug_message ( int message_level, int on_off );
Visual Basic
function lr.set_debug_message ( ByVal message_level as Integer,
ByVal on_off as
Integer ) as Integer
The lr_set_debug_message function sets the debug message level, message_lvl,
for the script
execution. By setting a message level, you determine which information is sent. The
setting is enabled
by passing LR_SWITCH_ON as on_off , and disabled with LR_SWITCH_OFF.
The messages are sent to the Application Management agent log or the LoadRunner
Vuser output.
Message levels are generally set in the script's Run-time Settings dialog box. The
value can be
changed from the current Run-time Settings value. For example, if the script's
current message level in
the Run-time Settings is set at "Brief" mode, the value can be increased to
"Extended
log" (LR_MSG_CLASS_EXTENDED_LOG):
l r _set _debug_message( LR_MSG_CLASS_EXTENDED_LOG, LR_SWI TCH_ON)
and later decreased to "Brief" once again:
l r _set _debug_message( LR_MSG_CLASS_EXTENDED_LOG, LR_SWI TCH_OFF)
To enable logging that is disabled in the Run-time Settings, set the message level to
another level. For
example:
l r . set _debug_message ( l r . MSG_CLASS_EXTENDED_LOG, l r . SWI TCH_ON) ;
After enabling the logging, return to the disabled state by setting the debug level to
zero (0) and
activating the option using the lr.SWITCH_ON switch as the second parameter.
The message levels Result Data, Parameter Substitution, and Full Trace, are specific
details, or subsettings,
of the Extended log setting. To set one of these sub-settings you can use logical Or's
in your
message_level argument.
Using LR_SWITCH_DEFAULT as on_off sets the on/off status of message_level to the
default value
regardless of previous calls to lr_set_debug_message. Use LR_SWITCH_DEFAULT
with a single
message_level argument. It does not work with ORed message_level settings.
message_level One of the Message Log Run-Time Settings.
on_off A switch to activate or deactivate a specific message level setting. Use one of
the
On-Off Constants.
Page 119 of 337
Page 120 of 337
lr_set_transaction
Creates a completed transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction
int lr_set_transaction(const char *name, double duration, int status);
Example See Also
Java Language
int lr.set_transaction( String name, double duration, int status);
Visual Basic
Function lr.set_transaction( String name, double duration, int status)
as integer
The lr_set_transaction function creates a transaction, its duration, and status in a
single call. Use it
where the business process you want to capture in a transaction does not consist of
sequential steps,
or where you may or may not want to create a transaction, depending on conditions
that are known
only during the test.
To create a transaction for non-sequential steps, capture the duration of each series
of steps that
participate in the business process. Sum the durations and create the transaction
with
lr_set_transaction.
To capture durations in C language scripts, use lr_start_timer and lr_end_timer. For
other languages,
use the native language time functions.
lr_set_transaction can also be used to report the duration of a failed transaction
by saving the
duration before the transaction fails with lr_get_transaction_duration then using
lr_set_transaction
to create a new transaction for reporting that time.
lr_set_transaction creates and closes the transaction. Therefore, no functions that
work only on
open transactions are applicable.
Note: Do not use the period character (.) in a transaction name. The period
character delimits
transactions and sub-transactions. In analysis, a transaction name with a period will
be interpreted as
two transactions.
Name A name for the transaction.
duration Transaction duration in seconds.
status The transaction completion status. One of theTransaction Status constants for
pass, fail,
or stop.
The auto status is not applicable.
Page 121 of 337
lr_set_transaction_instance_status
Sets the status of a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction_instance_status
int lr_set_transaction_instance_status (int status, long
trans_handle);
Example See Also
The lr_set_transaction_instance_status function sets the status of the open
transaction with the
transaction handle trans_handle. The handle was returned by
lr_start_transaction_instance .
This transaction's lr_end_transaction_instance statement must use automatic status
assignment by
passing a Transaction Status of auto as its status parameter.
A transaction's status is defined in the status parameter of
lr_end_transaction_instance. If this status
is LR_AUTO the value is automatically assigned. By default, this value is LR_PASS
signifying a
successful transaction. lr_set_transaction_instance_status changes this default
value to status.
For more information on transaction instances, see lr_start_transaction_instance.
status One of theTransaction Status constants for pass, fail, or stop.
trans_handle The handle to a transaction instance
Page 122 of 337
lr_set_transaction_status
Sets the default end status of open transactions.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction_status
int lr_set_transaction_status (int status);
Example See Also
Java Language
int lr.set_transaction_status ( int status);
The lr_set_transaction_status function sets the status of those transactions
currently open which
have LR_AUTO in their lr_end_transaction statement.
A transaction's status is defined in the status parameter of lr_end_transaction. If
this status is
LR_AUTO, the value is automatically assigned. By default, this value is LR_PASS,
signifying a
successful transaction. lr_set_transaction_status changes this default value to
status.
Page 123 of 337
lr_set_transaction_status_by_name
Sets the default end status of a single transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction_status_by_name
int lr_set_transaction_status_by_name (int status, const char
*trans_name);
Example See Also
The lr_set_transaction_status_by_name function sets the default status of the
open transaction
with name trans_name. This transaction's lr_end_transaction statement must use
automatic status
assignment by passing LR_AUTO as its status parameter.
A transaction's status is defined in the status parameter of lr_end_transaction. If this
status is
LR_AUTO, the value is automatically assigned. By default, this value is LR_PASS,
signifying a
successful transaction. lr_set_transaction_status_by_name changes this default
value to status.
trans_name The transaction name
Page 124 of 337
lr_start_sub_transaction
Starts a sub-transaction specified by its parent's name.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_sub_transaction
int lr_start_sub_transaction (const char *sub_transaction, const char
*parent_transaction);
Example See Also
Java Language
int lr.start_sub_transaction (String sub_transaction, String
parent_transaction);
Visual Basic
Function lr.start_sub_transaction (String sub_transaction, String
parent_transaction) as
Integer
The lr_start_sub_transaction function marks the beginning of a sub-transaction.
To mark the end of
the sub-transaction, use lr_end_sub_transaction. You insert these functions
immediately before and
after the sub-transaction actions.
Sub-transactions are used for isolating parts of a business process. For example, a
sub-transaction
"electrical_purchases" may be nested within the larger transaction "purchases." The
transaction
"purchases" is the parent transaction and "electrical_purchases" the sub-transaction.
Multiple sub-transactions can be nested within a parent transaction. A sub-
transaction may also be a
parent to a smaller sub–transaction.
The duration of a transaction or sub-transaction is the sum of the durations of all
steps between its
start and end, including the steps that are included in sub-transactions.
Each lr_start_sub_transaction statement must be matched with an
lr_end_sub_transaction
statement within the script or it will be interpreted as an illegal command.
Note: Do not use the period character (.) in a transaction or sub-transaction name.
The period
character delimits transactions and sub-transactions. In analysis, a transaction name
with a period
will be interpreted as two transactions.
sub_transaction The name of the sub-transaction
parent_transaction The name of the parent transaction in which the sub-transaction
is nested.
Page 125 of 337
lr_start_timer
Starts a timer.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_timer
merc_timer_handle_t lr_start_timer ();
Example See Also
lr_start_timer starts a timer that calculates the passage of time in seconds. The
resolution depends
on the run-time environment. The maximum resolution is a microsecond.
lr_start_timer returns a handle to the timer. Pass the handle to lr_end_timer to
stop the timer.
Page 126 of 337
lr_start_transaction
Marks the beginning of a transaction.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_transaction
int lr_start_transaction ( const char *transaction_name );
Example See Also
Java Language
int lr.start_transaction ( String transaction_name );
Visual Basic
function lr.start_transaction ( ByVal transaction_name as String ) as
Integer
The lr_start_transaction function marks the beginning of a transaction. To indicate
a transaction to
be analyzed, use the lr_start_transaction and lr_end_transaction functions. These
functions are
inserted immediately before and after the transaction.
Transactions can be nested, but each lr_start_transaction statement must be
associated with an
lr_end_transaction statement or it will be interpreted as an illegal command.
The period
with a period
Page 127 of 337
lr_start_transaction_instance
Starts a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_transaction_instance
long lr_start_transaction_instance ( const char *transaction_name,
long handle);
Example See Also
The lr_start_transaction_instance function marks the beginning of a transaction
instance. A
transaction instance is an occurrence of a transaction with transaction_name.
Instances are
identified by their handle which distinguishes them from other instances of the same
transaction.
This function enables multiple instances of a transaction to be created. Use
transaction instances
when the same transaction is required to be performed under different circumstances
and an analysis
of each circumstance is required.
By passing the handle of a parent transaction instance, the new instance will be
considered a subtransaction
instance of the parent. Pass zero as the handle if there is no parent. For more
information
on sub-transactions, see lr_start_sub_transaction.
The function returns the handle of the transaction instance which identifies the
instance. Note that
each lr_start_transaction_instance statement must be matched with an
lr_end_transaction_instance statement or it will be interpreted as an illegal
command.
The period
with a period
handle The parent transaction's handle. A value of 0 instructs VuGen to create a new
parent transaction.
Page 128 of 337
lr_stop_transaction
Freezes reporting of transaction data.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_stop_transaction
double lr_stop_transaction (const char *transaction_name);
Example See Also
Visual Basic
Function lr.stop_transaction ( String transaction_name ) as Double
This function is retained for backward compatibility. For more general ways of
reporting partial
transaction durations, see lr_start_sub_transaction, and lr_set_transaction.
After a call to lr_stop_transaction, statistics returned by the "get" Transaction
Functions reflect
only the data up to the call, until lr_resume_transaction is called. The specified
transaction must have
been opened with lr_start_transaction.
lr_resume_transaction, the "get"
functions return all data since the start of the transaction. Furthermore, the final
results when the
test is analyzed will reflect the total values, including the periods in between the
transaction stop and
resume.
If lr_resume_transaction is not called, the "get" functions and the final results
reflect only the
duration from the transaction start to the lr_stop_transaction call. Thus,
lr_stop_transaction and
lr_resume_transaction can be used conditionally to collect information either
about an entire
transaction, or only the beginning. To accomplish this, call lr_resume_transaction
only if your
condition is met.
Note: When data is collected this way, the data in analysis will reflect both the tests
where the
condition for lr_resume_transaction is met, and the tests where it is not.
If the section you may wish to exclude ends before the end of the transaction, this
technique does
not apply. If you need to differentiate between occurrences where the
condition is met and those where it is not in the analysis data, this technique does
not apply.
transaction_name The name of an open transaction.
Page 129 of 337
lr_stop_transaction_instance
Freezes reporting statistics for a transaction instance specified by its handle.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_stop_transaction_instance
double lr_stop_transaction_instance (long parent_handle);
Example See Also
After a call to lr_stop_transaction_instance, statistics returned by the "get"
Transaction Functions
reflect only the data up to the call, until lr_resume_transaction_instance is called.
The specified
transaction instance must have been opened with lr_start_transaction_instance.
lr_resume_transaction_instance, the
"get" functions return all data since the start of the transaction instance.
Furthermore, the final
results when the test is analyzed will reflect the total values, including the periods in
between the
transaction stop and resume.
If lr_resume_transaction_instance is not called, the final results reflect the
statistics only until the
call to lr_stop_transaction_instance.
The parent_handle is the value returned from the call to
lr_start_transaction_instance that created
the instance.
lr_stop_transaction_instance and lr_resume_transaction_instance can be
used to conditionally
collect information about either the beginning, or all of the transaction.
Note that you will not be able to differentiate in analysis between iterations when
lr_stop_transaction_instance was called and iterations where it was not.
For more flexible ways recording transaction times conditionally, see
lr_start_sub_transaction,
lr_set_transaction,and lr_start_timer.
lr_stop_transaction_instance returns the duration of the instance in seconds.
parent_handle A unique transaction handle.
Page 130 of 337
lr_think_time
Pauses execution between commands in a script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_think_time
void lr_think_time (double thinkTime);
Example See Also
Java Language
void lr.think_time ( double thinkTime );
Visual Basic
sub lr.think_time ( ByVal thinkTime as Double )
lr_think_time allows you to pause test execution during a run. This is especially
useful in simulating
think time, the time a real user pauses to think between actions.
thinkTime The length of the pause, in seconds.
Page 131 of 337
lr_user_data_point
Records a user-defined data sample.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point
int lr_user_data_point (const char *sample_name, double value);
Example See Also
Java Language
int lr.user_data_point ( String sample_name, double value );
Visual Basic
function lr.user_data_point ( ByVal sample_name as String, ByVal
value as double ) as
Integer
The lr_user_data_point function allows you to record your own data for analysis.
Each time you
want to record a point, use this function to record the sample name and the value.
The time that the
sample is recorded automatically. After the execution, you can use the User Defined
Data Points graph
to analyze the results.
Note: The following prefixes in sample_name are reserved:
HTTP
NON_HTTP
RETRY
mic_
stream_
mms_
A data point with any of these prefixes, for example "HTTP_BT", will not appear on
the graph.
However, the prefixes are case-sensitive, therefore "http_BT" is a valid
sample_name.
sample_name The data point name.
value The value to record.
Page 132 of 337
lr_user_data_point_ex
Records a user-defined data sample and enables logging option.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point_ex
int lr_user_data_point_ex ( const char *sample_name, double value,
int log_flag);
Example See Also
The lr_user_data_point_ex function is the same as lr_user_data_point except
for the additional
parameter log_flag.
Logging means writing data to a file. lr_user_data_point_ex enables you to write
a data point to the
Vuser log file. When run in VuGen, the output is output.txt
You may want to write the data point conditionally according to how important the
data to be logged
is. It can either be part of a Standard level when only the most important
information is logged or an
Extended level, when fuller logging is required.
log_flag denotes the log level and correlates to the settings found in VuGen's Log
runtime setting
which specifies how the script handles logging to a file during execution. If
DP_FLAGS_EXTENDED_LOG
is passed to lr_user_data_point_instance_ex then the data point is logged only
when the Extended
runtime Log setting is currently activate. If log_flag is DP_FLAGS_STANDARD_LOG
then it will be logged
only if the Standard setting is active. DP_FLAGS_NO_LOG indicates that this data
point is never
written to a log file.
sample_name A string indicating the name of the sample type.
log_flag Determines whether the data point should be logged or not:
DP_FLAGS_NO_LOG (1)
DP_FLAGS_STANDARD_LOG (2)
DP_FLAGS_EXTENDED_LOG (3)
Page 133 of 337
lr_user_data_point_instance
Records a user-defined data sample and correlates it to a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point_instance
long lr_user_data_point_instance (const char *sample_name, double
value, long
transaction_handle);
Example See Also
The lr_user_data_point_instance function is similar to lr_user_data_point except
for its
transaction_handle parameter which allows you to associate a data point with a
specific transaction
instance.
This function is intended for use with applications integrated with LoadRunner that
use transaction
instances.
For details on transaction instances, see lr_start_transaction_instance.
parent_handle A transaction instance identifier with which to associate the
data_point.
Page 134 of 337
lr_user_data_point_instance_ex
Records a user-defined data sample and correlates it to a transaction instance.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point_instance_ex
long lr_user_data_point_instance_ex (const char* sample_name,
double value, long
transaction_handle, int log_flag);
Example See Also
The lr_user_data_point_instance_ex function is the same as
lr_user_data_point_instance except
for the additional parameter log_flag.
Logging means writing data to a file. lr_user_data_point_instance_ex enables
you to write a data
point to the Vuser log file. When run in VuGen, the output is output.txt
You may want to write the data point conditionally according to the importance of
the data to be
logged. It can either be part of a Standard level when only the most important
information is logged or
an Extended level, when fuller logging is required.
log_flag denotes the log level and correlates to the settings found in VuGen's Log
runtime setting
which specifies how the script handles logging to a file during script execution. If
DP_FLAGS_EXTENDED_LOG is passed to lr_user_data_point_instance_ex then
the data point is
logged only when the Extended runtime Log setting is activate. If log_flag is
DP_FLAGS_STANDARD_LOG then it will be logged only if the Standard setting is
active.
DP_FLAGS_NO_LOG indicates that this data point is never written to a log file.
parent_handle A transaction instance identifier with which to associate the
data_point.
log_flag Determines whether the data point should be logged or not:
DP_FLAGS_NO_LOG (1)
DP_FLAGS_STANDARD_LOG
DP_FLAGS_EXTENDED_LOG (3)
Page 135 of 337
lr.vuser_group
Returns the name of the Vuser group.
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.vuser_group
Function lr.vuser_group ( ) as String
The lr.vuser_group function returns the name of the Vuser group to which the
Vuser belongs.
Page 136 of 337
lr.vuser_id
Returns the Vuser ID.
HP LoadRunner Online Function Reference > Utility Functions: VB, VB Script (lr.) > lr.vuser_id
Function lr.vuser_id ( ) as Long
The lr.vuser_id function returns the ID of the running Vuser.
Page 137 of 337
lr_vuser_status_message
Sends a message to the Vuser status area.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_vuser_status_message
int lr_vuser_status_message (const char *format);
Example See Also
Java Language
int lr.vuser_status_message ( String message );
Visual Basic
Function lr.vuser_status_message ( message As String ) as Integer
The lr_vuser_status_message function sends a string to the Status area of the
Controller. It also
sends this string to the Vuser log. When run from VuGen, the message is sent to
output.txt.
Page 138 of 337
lr_wasted_time
Removes wasted time from all open transactions.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_wasted_time
void lr_wasted_time (long wasteTime);
Example See Also
Other languages
See lr_set_transaction for an alternative.
lr_wasted_time allows you to subtract the time wasted on incidental or secondary
actions from all
open transactions.
For more information, see Wasted Time.
wasteTime The time in milliseconds to be removed from all open transactions.
Page 139 of 337
lr_whoami
Returns information about the Vuser executing the script.
C Language
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_whoami
void lr_whoami (int *vuser_id, char **sgroup, int *scid);
Example See Also
The lr_whoami function gets information about the Vuser.
Note that the sgroup parameter is a pointer to constant data and should only be
read, not altered.
Memory for the string is allocated automatically. You do not have to allocate
explicitly in the script.
If you do not want to retrieve one or more of the parameters, replace the parameter
name with NULL.
Not applicable for products that do not run individual Vusers.
vuser_id A pointer to an output argument to store the Vuser ID number.
sgroup A pointer to an output argument to store the name of the Vuser Group.
scid A pointer to an output argument to store the Scenario or Session step ID
number.
Page 140 of 337
Message Formatting
The first character of the format parameter is always a percent sign (%). The last
character of
format is a letter code that determines the type of formatting. One or more format
modifiers can
appear between the first and last character of the format argument (see below). The
possible letter
codes are as follows:
Note that a separate formatting specification must be provided for each expression
to be printed. For
example, the statement:
printf("My name is %s%s\n", "Arthur", "Dent");
prints the statement "My name is Arthur Dent" to standard output. Without the
second "%s," the
second expression (Dent) would have been ignored.
The output generated by a particular formatting code can be modified. Three types
of modifiers can
appear between the percent sign (%) and the format code character:
HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > Message Formatting
Character Argument
Type
Printed As
d,i int decimal number
o int unsigned octal number without a leading zero
x,X int unsigned hexadecimal number without a leading 0x
u int unsigned decimal number
c int single character
s char * print characters until either `\0' or the number of characters given in
the precision is reached
e,E double engineering notation (m.dddddd e+exponent). If precision is greater
than fractional part, prints trailing zeros
g,G double engineering notation without trailing zeros or trailing decimal point
% none print the character `%'
-
(justification)
A hyphen (-) indicates that the printed output is to be left justified in its field.
field width A number, by itself or to the left of a decimal point, indicates how many
characters
the field should be padded. When this number is preceded by a 0, the padding
occurs with zeros to the left of the printed value.
precision A number to the right of a decimal point indicates the maximum width of
the printed
string or how many digits are printed to the right of the output decimal point.
Page 141 of 337
Message Log Run-Time Settings

There are three main settings for run-time message logging:
The following are "ORed" with the Extended Log message setting used to further
refine the setting:
This setting can be "ORed" with all other message setting:
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Message Log Run-Time Settings
Log Level C Language
Constants
Object Oriented Constants Value
Disabled LR_MSG_CLASS_
DISABLE_LOG
lr.MSG_CLASS_
DISABLE_LOG
0
Brief LR_MSG_CLASS_
BRIEF_LOG
lr.MSG_CLASS_
BRIEF_LOG
1
Extended Log LR_MSG_CLASS_
EXTENDED_LOG
lr.MSG_CLASS_
EXTENDED_LOG
16
Constants
Result Data LR_MSG_CLASS_
RESULT_DATA
lr.MSG_CLASS_
RESULT_DATA
2
Parameter
Substitution
LR_MSG_CLASS_
PARAMETERS
lr.MSG_CLASS_
PARAMETERS
4
Full Run-Time
Trace
LR_MSG_CLASS_
FULL_TRACE
lr.MSG_CLASS_
FULL_TRACE
8
Constants
Object Oriented
Constants
Value
Only on error.
Which messages sent on error depends on
other settings.
LR_MSG_CLASS_
JIT_LOG_ON_
ERROR
lr.MSG_CLASS_
JIT_LOG_ON_
ERROR
512
Page 142 of 337
On-Off Constants
These are the constants for activating and deactivating settings:
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > On-Off Constants
Action C Language
Constants
Turns the setting off. LR_SWITCH_
OFF
lr.SWITCH_
OFF
0
Turns the setting on. LR_SWITCH_
ON
lr.SWITCH_
ON
1
Uses the defaults from the script's cfg file. LR_SWITCH_
DEFAULT
lr.SWITCH_
DEFAULT
2
Page 143 of 337
Parameterization Background
For information about the arguments that are available for parameterization, click
the
Parameterization button in that function.
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Parameterization Background
Page 144 of 337
Raw Body Attribute

Binary content can be sent in the request using the BodyBinary attribute (or the
Body attribute
when "Binary=1" is also specified). However, this method requires that content is
converted into ASCII
text using escape backslashes for non–printable text.
To enable a more simple representation of the raw data, the Raw Body attribute
instead enables you
to pass a pointer to the binary content.
The syntax for sending raw body content is a set of 4 arguments to
web_custom_request(). They
must appear in the following order:
The correct order is:
RAW_BODY_START,
a poi nt er t o t he dat a buf f er ,
( i nt ) l engt h,
RAW_BODY_END
The syntax is illustrated in the following example:
char *abc= . . . / * a poi nt er t o t he r aw dat a */
web_cust om_r equest ( "St epName" ,
"URL=ht t p: / / some. ur l " ,
"Met hod=POST" ,
RAW_BODY_START,
" abc" ,
3,
RAW_BODY_END,
LAST) ;
The pointer data buffer must not be NULL, even when the length is 0.
The Raw Body group cannot be used with the Binary parameter set ("Binary=1").
The data buffer cannot be parameterized. That is, any parameter reference (e.g.,
"{MyParam}") in the
data buffer will not be substituted with the corresponding parameter value, and will
be used as is.
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Raw Body Attribute
Page 145 of 337
Script Continuation Options

Scripts exit with one of these options for continuation:
Note: The behavior of LR_EXI T_MAI N_I TERATION_AND_CONTI NUE and
LR_EXI T_I TERATION_AND_CONTI NUE changed between versions 8.0 and 8.1.
These options can be
configured by using these run options:
-main_iteration_exit: Both LR_EXI T_MAI N_I TERATION_AND_CONTI NUE and
LR_EXI T_I TERATION_AND_CONTI NUE behave like LR_EXI T_MAI N_I
TERATION_AND_CONTI NUE. Thi s
was t he behavi or bef or e ver si on 8. 1.
-block_iteration_exit: Both LR_EXI T_MAI N_I TERATION_AND_CONTI NUE and
LR_EXI T_I TERATION_AND_CONTI NUE behave like LR_EXI T_I
TERATION_AND_CONTI NUE
Add these flags in the [action_logic] section in mdrv.dat:
ExtCmdLine=-main_iteration_exit
or
ExtCmdLine=-block_iteration_exit
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Script Continuation Options
C Constants Object Oriented
Constants
Behavior
LR_EXIT_VUSER lr.EXIT_VUSER Exit without any condition, and go directly to end
action
LR_EXIT_ACTION_
AND_CONTINUE
lr.EXIT_ACTION_
AND_CONTINUE
Stop current action, and go to the next action.
LR_EXIT_MAIN_
ITERATION_
AND_CONTINUE
lr.EXIT_MAIN_
ITERATION_
AND_CONTINUE
Stop current global script run iteration, and go to
the next iteration.
LR_EXIT_ITERATION_
AND_CONTINUE
lr.EXIT_ITERATION_
AND_CONTINUE
Stop current iteration, and go to the next iteration.
If called from within a block iteration, only the block
iteration will be exited, and not the global iteration.
LR_EXIT_VUSER_
AFTER_ITERATION
lr.EXIT_VUSER_
AFTER_ITERATION
Run until the end of the current iteration and then
exit.
LR_EXIT_VUSER_
AFTER_ACTION
lr.EXIT_VUSER_
AFTER_ACTION
Run until the end of the current action and then
exit.
Page 146 of 337
Script Exit Status

Scripts exit with one of these statuses:
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Script Exit Status
C Constants Object Oriented Constants
LR_PASS lr.PASS
LR_FAIL lr.FAIL
LR_AUTO lr.AUTO
Page 147 of 337
Transaction Status
Transactions complete with one of these statuses. The status can be read before
completion, but
may change at any time until the transaction completes.
HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Transaction Status
C Constants Object Oriented Constants
LR_PASS lr.PASS
LR_FAIL lr.FAIL
LR_AUTO lr.AUTO
LR_STOP lr.STOP
Visual Basic Syntax
String Arguments
Argument Lists
Special Characters

Command Line Parsing Functions: Page 1 of 337

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Command Line Parsing Functions: Page 1 of 337

Uploaded by

Copyright:

Available Formats

Page 1 of 337

Command Line Parsing Functions

String and Parameter Functions

lr_get_host_name Returns the name of the host executing the script.

lr_set_transaction Create a transaction manually.

Note: Do not send null pointers as arguments to string formats e.g.

Rendezvous Return Values

Saves an integer to a parameter.

Page 120 of 337

Message Log Run-Time Settings

Page 144 of 337

Raw Body Attribute

Page 145 of 337

Script Continuation Options

Script Exit Status

You might also like