Lr Functions

Page 1 of 337Command 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 Click one of the following functions for more information: 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 Click one of the following functions for more information: 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 Application Management agent log file. 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 Click one of the following functions for more information: 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 Click one of the following functions for more information: 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 Click one of the following functions for more information: 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. Click one of the following functions for more information: 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 Click one of the following functions for more information: 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 Application Management agent log file. 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_instance_status Sets the status of a transaction instance. 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 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_user_data_point Records a user-defined data sample. When you end a run using this function.abort( ). Example See Also Java Language void lr. the status is "Stopped. Example See Also Java Syntax The lr_abort function aborts the execution of a script .advance_param ( ByVal parameter as string ) as integer Example See Also Visual Basic Syntax . and ends the execution." Page 50 of 337 lr_advance_param C Language Advances to the next available parameter value. lr_whoami Returns information about a Vuser executing the script Page 11 of 337 lr_abort Aborts the execution of a script. lr_user_data_point_ex Records a user-defined data sample.advance_param ( String parameter ). Example See Also Java Syntax Visual Basic function lr. lr_vuser_status_message Sends a message to the Vuser status area in the Controller.lr_think_time Pauses execution between commands in a script. executes the vuser_end section. lr_user_data_point_instance_ex Records a user-defined data sample and correlates it to a transaction instance. Example See Also Java Language int lr. It stops the execution of the Actions section. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_advance_param Return Values Parameterization int lr_advance_param ( const char *param). C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_abort Return Values Parameterization void lr_abort( ). This function is useful when you need to manually abort a run as a result of a specific error condition. lr_wasted_time Removes wasted time from all open transactions. lr_user_data_point_instance Records a user-defined data sample and correlates it to a transaction instance. Valid values: false: Steps do not fail. Page 52 of 337 lr_continue_on_error . "StopOnValidationError=<error_code>". "ActualValue={<input_param>}". Example See Also The lr_checkpoint function validates the value of a parameter against a checkpoint value. This function is not recorded. param The name of the parameter in quotes (no brackets). Can be a value or a LoadRunner parameter. Can be a value or a LoadRunner parameter. StopOnValidationError Indication of whether all steps fail. you can specify in the parameter properties to advance automatically to the next value for each iteration. The effect on other parameters in the same data file depends on the settings in the Vuser parameter list dialog. This function is not recorded—you insert it manually into your script. Operators are case-sensitive. as it appears in the test tree. The Continue on Error? runtime setting takes precedence over the value of StopOnValidationError. ActualValue Data to compare with the ExpectedValue argument. the script aborts or continues. Compare Operator used to compare the ActualValue and ExpectedValue values: Equals NotEquals Contains StartsWith EndsWith ExpectedValue Data to compare with the ActualValue argument. depending on the values of the StopOnValidationError argument and the Continue on Error? runtime setting. Page 51 of 337 lr_checkpoint Validates the value of a parameter against an expected value (checkpoint). "Compare=<operator>".The lr_advance_param function causes the script to use the next available value of the parameter. Use this function within an iteration to advance to the next value. LAST This delimiter marks the end of the argument list. If you are running multiple iterations. See the Example. If the validation fails. StepName The name of the step. "ExpectedValue={<checkpoint>}". It can be added manually when enhancing the script. true: Steps fail. LAST). C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_checkpoint Return Values Parameterization int lr_checkpoint("StepName=<step_name>". Any text can be used. select the Continue on Error check box in VuGen's Runtime Settings. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_continue_on_error Return Values Parameterization void lr_continue_on_error ( int value ). and UTF-8. value One of the Error Continuation Options. Unicode. In addition to the lr_continue_on_error statements. you can control error handling for a specific segment of the script. By default. 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" . C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_convert_string_encoding Return Values Parameterization int lr_convert_string_encoding ( const char *sourceString. Page 53 of 337 lr_convert_string_encoding Converts a string to a different encoding. in the parameter paramName. you can use severity levels to control error handling for database operation errors in LoadRunner. Example See Also lr_convert_string_encoding converts a string encoding between the following encodings: System locale. including its terminating NULL. Normally. the script exits when an error occurs. by inserting the lr_continue_on_error function before and after the desired segment (see the example for details). You can choose to continue running if an error occurs.Specifies an error handling method. const char *paramName). To continue script execution even when errors occur. The function saves the result string. lr_convert_string_encoding is added manually to a script when needed. Example See Also The lr_continue_on_error function specifies how to handle errors. const char *fromEncoding. you specify how the test run component handles errors during script execution using the General section in VuGen's Runtime Settings dialog. However. const char *toEncoding. or to abort the run execution. It is not recorded. Tip: Use the Connection Dialog to create a database specific connection string. When specifying the connection string using SQL Server 2005 Express. ConnectionString A string indicating the database to which to connect and other information needed to establish the connection. ConnectionString could contain the value: Dat a Sour ce=mySer ver Addr ess. The password cannot be encrypted. "ConnectionName=<connection_name>". Note that the equal signs are part of the connection string. the Microsoft Native SQL Provider) OLEDB ODBC ORACLE LAST This delimiter marks the end of the argument list. use the server name syntax <SQL Server 2005 Express installation>\SQLEXPRESS. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_connect Return Values Parameterization int lr_db_connect("StepName". Page 55 of 337 . Example See Also The lr_db_connection function establishs the database connection used by other database related functions. . ConnectionType Type of data provider. escaping the backslashes in the path. to connect to an SQL Server.Dat abase=. Any text can be used. "ConnectionString=<connection_string>". The syntax for the connection string varies depending on the data provider specified with the ConnectionType argument. Passwor d=myPasswor d. For example. use the server and instance name in the data source. Select the Database: Connect option in the Add Step dialog box and enter the connection parameters. "ConnectionType=<connection_type>". . For example: "Connect i onSt r i ng=Ser ver=soa-m16\ \ soa. Adding this function to the Action section can increase performance overhead during load testing. Add lr_db_connect to the vuser_init section of the script. ConnectionName A logical name for the connection. StepName The name of the step. I ni t i al Cat al og=myDat abase I d=myUser .Page 54 of 337 lr_db_connect Connects to a database. such as lr_db_executeSQLStatement . When specifying the connection string for a specific SQL Server instance. LAST). as it appears in the test tree. Valid values are: SQL (meaning. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_dataset_action Return Values Parameterization int lr_db_dataset_action("StepName=<step_name>". StepName The name of the step. Example See Also The lr_db_disconnect function disconnects a database connection. as it appears in the test tree. as it appears in the test tree. Page 57 of 337 lr_db_executeSQLStatement Submits an SQL statement to a database. removes it from memory. Example See Also The lr_db_dataset_action function sets the cursor to the first record of the dataset. The total number of records is also listed. Action The action to perform on the dataset: RESET: Set the cursor to the first record of the dataset. . Any text can be used. only the first one hundred records are listed in the test report summaries. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_executeSQLStatement Return Values Parameterization int lr_db_executeSQLStatement("StepName=<step_name>". PRINT: Prints the contents of the entire dataset to the Replay Log and other test report summaries. StepName The name of the step. "ConnectionName=<connection_name>". Add lr_db_disconnect to the vuser_end section of the script. "Action=<action>". Any text can be used.lr_db_dataset_action Performs an action on a dataset. LAST). HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_disconnect Return Values Parameterization int lr_db_disconnect("StepName=<step_name>". Page 56 of 337 lr_db_disconnect C Language Disconnects from a database. When printing a dataset. LAST This delimiter marks the end of the argument list. LAST). or prints the dataset to the Replay Log. DatasetName Logical name for the dataset specified in lr_db_executeSQLStatement . You must call lr_db_disconnect for each connection established by lr_db_connect to terminate the connection. 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 . "DatasetName=<dataset_name>". LAST This delimiter marks the end of the argument list. REMOVE: Releases the memory allocated for the dataset. Any text can be used. DatasetName Logical name for the resulting dataset from the SQL query. StepName The name of the step. or UPDATE. as it appears in the test tree. such as SELECT. make sure to set Row to next or 1 if calling lr_db_getValue after this function. LAST This delimiter marks the end of the argument list. LAST). The data in the dataset can be manipulated by subsequent steps in the script. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_db_getValue Return Values Parameterization int lr_db_getValue("StepName=<step_name>". This function does not support the print or output of binary data. DatasetName points to the resulting dataset."ConnectionName=<connection_name>". the term dataset is used to describe tables of data (formatted as rows and columns). SQLStatement The SQL statement. 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. Binary values retrieved from the dataset appear as <binary_data>. In this case. . When SQLStatement is a SELECT statement. INSERT. SQLStatement can be parameterized. In this context. the row is undefined. Column The name of the column in the dataset from which to retrieve the value. a warning is issued to the Replay Log and the test results summary.] LAST). DatasetName Logical name for the dataset specified in lr_db_executeSQLStatement . "DatasetName=<dataset_name>". If Row=next is specified the next time lr_db_getValue is called. Page 58 of 337 lr_db_getValue Retrieves a value from a dataset. ConnectionName The logical name for the connection specified in lr_db_connect . StepName The name of the step. by which you can refer to the dataset in subsequent steps. Example See Also The lr_db_executeSQLStatement submits an SQL statement to a database. "SQLStatement=<statement>". Any text can be used. and UPDATE. For use only when SQLStatement is a SELECT statement. DELETE. INSERT. After calling this function. "Column=<column>". ["DatasetName=<dataset_name>". as it appears in the test tree. The syntax is database-dependent. "Row=<row>". "OutParam=<output_parm>". When SQLStatement is either DELETE. the script continues to the first record without issuing any errors. .. You may use the standard Message Formatting that is available for printf.Row Sets the dataset cursor to the specifed row before fetching data. The message is sent to the output window.does not move the cursor next . To determine the current level. format A formatted string which is the message to be sent to the log file.debug_message ( int message_level. Page 59 of 337 lr_debug_message Sends a debug message to the log file. One of: The row number (1-based) current . a message is not issued. Activate Expert Mode (Tools > Expert Mode) and then choose Tools > Options > Debug Information and select the General check box. LAST This delimiter marks the end of the argument list. Page 60 of 337 .debug_message ( ByVal message_level as Integer. message_level One of the Message Log Run-Time Settings. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_debug_message Return Values Parameterization int lr_debug_message (unsigned int message_level. the message is issued to the Output window. Disabled does not apply.. const char *format. the message is not issued. If none of the levels are active. ). use lr_get_debug_message. Example See Also Java Language int lr. String message ). Example See Also Java Syntax Visual Basic function lr. If the specified message level is not active. ByVal message as string ) as Integer Example See Also Visual Basic Syntax The lr_debug_message function sends a debug message when the specified message level is active. Note that you can also specify multiple message levels with an OR separator ("|"). If any one of the levels are active (from the UI). 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. use the Expert Mode Settings. To display the debug messages in the LoadRunner output window or Application Management agent log file.sets the cursor to the next row OutParam The LoadRunner parameter that will contain the value. copy the recorded value. Then run Start > Programs > LoadRunner > Tools > Password Encoder. not including the quote marks themselves. The original string is replaced with an lr_decrypt call where the EncodedString argument is the original string after encoding. VuGen encrypts the password differently. Example See Also Java Syntax Visual Basic function lr. Page 62 of 337 . This function is generated during recording to encode passwords. Click the Copy button. When you run the script. the test run component decrypts the password. Right-click in the selected string and choose the ENCRYPT STRING option. even when you use the same password. then paste the encryped string into a parameter for later use. Paste the value into the Password field. and click Generate.decrypt ( String EncodedString ). The encrypted string appears in the Encoded string box. VuGen records the actual password but displays an encoded version of the password within the lr_decrypt function. Each time you record.lr_decrypt Decrypts an encoded string C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_decrypt Return Values Parameterization char *lr_decrypt (const char *EncodedString). Example See Also lr_disable_ip_spoofing disables IP spoofing during a script run. Select an entire string between quote marks.decrypt ( ByVal EncodedString as String ) as String Example See Also Visual Basic Syntax The lr_decrypt function decrypts an encoded string. EncodedString The encoded string you want to decrypt. VuGen uses 32 bit encryption. Example See Also Java Language String lr. To get an encryped value from a recorded value for later use. or assign the value to a string variable. It is possible to create an lr_decrypt call from a recorded value in the script. 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 Return Values Parameterization int lr_disable_ip_spoofing ( ). status as Integer ) as Integer Example See Also Visual Basic Syntax The lr_end_sub_transaction function marks the end of a sub-transaction.empty Returns an Variant whose value is Empty. use the lr_start_sub_transaction function.) > lr. VB.end_sub_transaction ( sub_transaction as String. Java Script HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr.lr. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_sub_transaction Return Values Parameterization int lr_end_sub_transaction (const char *sub_transaction. int status ). To mark the beginning of the sub-transaction.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 Return Values Parameterization int lr_enable_ip_spoofing ( ). Multiple sub-transactions can be nested within a parent transaction. Example See Also Java Language int lr. Example See Also VB Script Function lr.NET or C#. use the class or keyword Empty. int status ). In Visual Basic. Example See Also lr_enable_ip_spoofing enables IP spoofing during a script run. Example See Also Java Syntax Visual Basic function lr.empty Return Values Parameterization Variant lr. Page 64 of 337 lr_end_sub_transaction Marks the end of a sub-transaction. Example See Also Use lr.empty () as Variant.empty to pass an Empty variant to a function that requires a Variant argument. but each . You insert these functions immediately before and after the sub-transaction steps.end_sub_transaction ( String sub_transaction. 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). It returns the elapsed time in seconds. Example See Also Java Language int lr. To indicate a transaction to be analyzed. Example See_Also lr_end_timer stops a timer that began timing when lr_start_timer was called. Page 65 of 337 lr_end_timer Stops a timer. set the status .end_transaction ( ByVal transaction_name as string. For the "succeed" return code. int status ) . Example See Also Java Syntax Visual Basic function lr. The resolution depends on the run-time environment. int status ).end_transaction ( String transaction_name. you perform a manual check within the code of your script (see example) evaluating the return code of a function. status The transaction status. To manually set the status. and the lr_end_transaction function after the transaction.lr_end_sub_transaction statement must match an lr_start_sub_transaction statement or it will be interpreted as an illegal command. timer The handle of the timer returned by lr_start_timer. ByVal status as Integer ) as Integer Example See Also Visual Basic Syntax The lr_end_transaction function marks the end of a transaction and records the amount of time it took to perform the transaction. Page 66 of 337 lr_end_transaction Marks the end of a transaction. You can manually set the status of the transaction or you can allow the script to detect it automatically. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_transaction Return Values Parameterization int lr_end_transaction (const char *transaction_name. The maximum resolution is a microsecond. place the lr_start_transaction function before the transaction. sub_transaction A string indicating the name of an existing sub-transaction. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_end_transaction_instance Return Values Parameterization int lr_end_transaction_instance (long parent_handle. Page 68 of 337 lr_error_message . status The transaction status. To instruct the script to automatically detect the 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. lr_set_transaction_instance_status or lr_fail_trans_with_error. If you make a series of calls to functions that modify the LR_AUTO status. set the status to LR_FAIL. status The Transaction Status Page 67 of 337 lr_end_transaction_instance Marks the end of a transaction instance. then this is the value which is passed as status in lr_end_transaction. set the transaction status to LR_PASS. For the "succeed" return code. 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. you perform a manual check within the code of your script (see example) evaluating the return code of a function. For a "fail" return code. However.to LR_PASS. If status is LR_AUTO. place the lr_start_transaction_instance function before the transaction. For an "aborted" return code. You can manually set the status of the transaction instance or you can allow the script to detect it automatically. and the lr_end_transaction_instance function after the transaction. specify LR_AUTO. if prior to lr_end_transaction. int status ). lr_set_transaction_status_by_name. set the status to LR_FAIL. parent_handle The handle returned by lr_start_transaction_instance at the creation of the instance. To indicate a transaction instance to be analyzed. set the status to LR_STOP. set the status to LR_STOP. To manually set the status. By default. For an "aborted" return code. The script returns the detected. you change the default value using lr_set_transaction_status. then the value of status is automatically assigned. this value is LR_PASS signifying a successful transaction. For a "fail" return code. ).error_message ( String message ). log files (such as Vugen and the Application Management agent log file). To issue a message without those details. use lr_output_message. and other test report summaries. use lr_message.Act i on( 4) : out put message Out put of l r _message( "message" ) . see the products' user guides.error_message ( ByVal message as String ) as Integer Example See Also Visual Basic Syntax The lr_error_message function sends an error message to product output windows (such as the LoadRunner output window). . To send a special notification that is not specifically an error message. as it will lengthen the execution time. log files.. and other test report summaries. It is not recommended that you send a message to the Output window in the middle of a transaction. use lr_log_message to send the message only to the Vuser log file. exp2. If you want to save the elapsed time in spite of the transaction failure. using Error code 17999. int lr_error_message (const char *format. calling lr_error_message will fail the transaction in addition to sending the message.Sends an error message with location details to the output windows. You may specify a literal string in quotation marks or use the standard Message Formatting that is available for printf..expn. Note that this function sends a message to the output even when logging is disabled in the run-time settings. . Out put of l r _er r or _message( " out put message" ) . For details regarding the output for each product. message format C Language A formatted string to send to the Output window.. 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. this function lists the location and line number from where the message was issued. capture the time with lr_get_transaction_duration before calling lr_error_message. In the Vuser Execution log. exp1. then create a transaction to report the time with lr_set_transaction. Example See Also Java Syntax Visual Basic function lr. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_error_message Return Values Parameterization Example See Also Java Language int lr. Instead. If Run-time settings > General > Miscellaneous > Fail open transactions on lr_error_message is selected. Visual Basic and VB Script Return Values Parameterization HP LoadRunner Online Function Reference > Utility Functions: VB. param_name The parameter to evaluate.exp 1 . Page 69 of 337 Page 70 of 337 lr.) > lr.eval_double (ByVal param_name as String ) as Double Example See Also Visual Basic Syntax The lr. Example See Also Java Language String lr. Page 72 of 337 lr_eval_string Returns the string argument after evaluating embedded parameters.eval_long Return Values Parameterization function lr. message Java and Visual Basic A string containing the error message to send to the Output window.eval_long (ByVal param_name as String ) as long Example See Also Visual Basic Syntax The lr. VB Script (lr.eval_long function returns the value of the parameter as a Long. .) > lr.eval_double function lr... exp n C Language The expressions or variables to be formatted.eval_double function returns the value of the parameter as a double param_name The parameter to evaluate. exp 2 . VB Script (lr. Visual Basic and VB Script HP LoadRunner Online Function Reference > Utility Functions: VB. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string Return Values Parameterization char *lr_eval_string (const char *instring ).eval_long Returns the long value of the parameter. Page 71 of 337 lr. See VB String Arguments and Java String Arguments.eval_string ( String instring ).eval_double Returns the double value of the parameter. . Note: lr_eval_string allocates memory internally. unsigned long const in_len. Note that in_len is the length of the argument you pass. For example. If you evaluate a parameter or parameters in a loop. Use this function in conjunction with lr_eval_string_ext_free in preference to lr_eval_string when evaluating strings in a loop. unsigned long const options. the function returns the current value of the parameter. The memory is freed at the end of each iteration. if parameter ABC contains the string "1234567890". const char *file. use lr_eval_string_ext and free the memory in each loop iteration with lr_eval_string_ext_free. Embedded parameters must be in brackets. Instead. It also assigns the length of the buffer to out_len. for example. and not the length of the value of the parameter. unsigned long * const out_len. conserve memory by not using lr_eval_string . in_str The string to be evaluated. 5 After using lr_eval_string_ext. instring The string to evaluate.eval_string (ByVal instring as String ) as String Example See Also Visual Basic Syntax The lr_eval_string function returns the input string after evaluating any embedded parameters. If the string argument contains only a parameter. data with embedded NULL characters. the call is: l r _eval _s t r i ng_ext ( "{ABC}" . This function is useful when correlating statements that use binary data. long const line ). It creates a buffer containing the expanded string and sets out_str to point to that buffer. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string_ext Return Values Parameterization int lr_eval_string_ext (const char *in_string. free the memory allocated for the output buffer with lr_eval_string_ext_free. Example See Also The lr_eval_string_ext function evaluates in_str by replacing parameters with their string value. char ** const out_str.Example See Also Java Syntax Visual Basic function lr. Page 73 of 337 lr_eval_string_ext Creates a buffer and assigns it the input string after evaluating embedded parameters. Using lr_eval_string in a loop uses more memory. Currently set to "-1". out_len The length of the output buffer. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_exit Return Values Parameterization void lr_exit (int continuation_option. Currently set to "0". Currently set to "0". int exit_status). Example See Also Java Syntax The lr_exit function allows you to exit from the script run during execution. it is the exit status of the last call that determines the status of the Vuser group running the script. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_eval_string_ext_free Return Values Parameterization void lr_eval_string_ext_free (const char **param). .exit (int continuation_option. file Reserved for future use. The controller's Scenario Groups Status box displays the status. Page 74 of 337 lr_eval_string_ext_free Frees the buffer allocated by lr_eval_string_ext.in_len The length of the name of argument in_str +2 to account for the parentheses. options Reserved for future use. or iteration. action. int exit_status). It is ignored in the count of passed and failed transactions. Page 75 of 337 lr_exit Exits from the script. line Reserved for future use. whether in different actions or different iterations. 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. Example See Also Java Language void lr. Example See Also The lr_eval_string_ext_free function frees the memory allocated by lr_eval_string_ext . out_str A pointer to the output buffer. If lr_exit is called several times in the same script. param A pointer to the buffer. It is the column in which the group appears after the run stops. A transaction in which lr_exit is called does not appear in the LoadRunner controller in the Transaction Status box. exp 2 .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. exp n The optional expressions (variables) to be formatted and printed. Page 77 of 337 lr_get_attrib_double C Language Return Values Parameterization Returns a value of the calling mdrv command's parameter as a double.get_attrib_double ( String parameter ).. exp 1 .. If it is a literal string. exp2. 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. lr_fail_trans_with_error changes this default value to LR_FAIL. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_double double lr_get_attrib_double (const char *parameter). exp n . You may specify a literal string in quotation marks or use the standard Message Formatting that is available for printf. By default the value assigned is LR_PASS. Example See Also Java Language double lr.. enclose it with quotation marks.). exp 2 . A transaction's final status is defined in the status parameter of the lr_end_transaction statement. The message is sent to the LoadRunner output window or Application Management agent log file... exp1. then the value is automatically assigned. If this status is LR_AUTO. Use the format and exp parameters in the same way as the standard Message Formatting that is available for printf. . format A string describing the format to use to write the optional remaining expressions exp 1 .expn... which signifies a successful transaction. Example See Also Java Syntax Visual Basic function lr.Example See Also Visual Basic function lr. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_long Return Values Parameterization long lr_get_attrib_long (const char *parameter). see the HP LoadRunner Virtual User Generator User Guide. the script was run directly in VuGen or by LoadRunner). For more information on the running scripts using the mdrv command line. Page 79 of 337 . 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 script was run directly in VuGen or by LoadRunner). 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. For more information on the running scripts using the mdrv command line. parameter The name of a parameter which can be interpreted as a double value.get_attrib_long ( ByVal parameter as String ) as long Example See Also Visual Basic Syntax 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. Page 78 of 337 lr_get_attrib_long C Language Returns a value of the calling mdrv command's parameter as a long integer. The Command Line Parsing Functions functions eliminate the need to parse the command line manually. The function returns NULL if the mdrv command line was not used to run the script (for example. see the HP LoadRunner Virtual User Generator User Guide. You place the command line parameter name in the function's argument field and lr_get_attrib_long returns the value of that parameter. The function returns NULL if the mdrv command line was not used to run the script (for example.get_attrib_double ( ByVal parameter as String ) as double Example See Also Visual Basic Syntax 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.get_attrib_long ( String parameter ). Example See Also Java Language long lr. You place the argument name in the function's argument field and lr_get_attrib_string returns the string values associated with that argument. Example See Also Java Syntax Visual Basic function lr. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_attrib_string Return Values Parameterization char *lr_get_attrib_string (const char *argument). The log settings are specified with the run-time settings dialog. . argument A command line argument whose value is a string. This is useful for checking if a command line option or a specific value is valid. The Command Line Parsing Functions functions eliminate the need to parse the command line manually.get_attrib_string ( String parameter ). or by using the lr_set_debug_message function.get_attrib_string ( ByVal parameter as String ) as String Example See Also Visual Basic Syntax The lr_get_attrib_string function returns a command line argument string when the script is run using the mdrv command. Page 80 of 337 lr_get_debug_message C Language Return Values Parameterization Returns the current message logging settings. Example See Also Java Syntax Visual Basic function lr. The function returns NULL if the argument you specify is invalid. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_debug_message unsigned int lr_get_debug_message ( ). The function returns NULL if the mdrv command line was not used to run the script (for example.lr_get_attrib_string Returns a value of the calling mdrv command's parameter as a string. Example See Also Java Language int lr.get_debug_message ( ) as Integer Example See Also Visual Basic Syntax The lr_get_debug_message function returns the current log run-time settings . see the HP LoadRunner Virtual User Generator User Guide. the script was run directly in VuGen or by LoadRunner). Example See Also Java Language String lr. The settings determine what information is sent output. For more information on the running scripts using the mdrv command line.get_debug_message ( ). Page 83 of 337 lr_get_transaction_duration Returns the duration of a transaction. Page 81 of 337 lr_get_host_name Returns the name of the host. See the C syntax example. Not applicable for products that do not run Vusers.get_host_name ( ) as String Example See Also Visual Basic Syntax The lr_get_host_name function returns the name of the machine executing the script. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_duration Return Values Parameterization .The debug messages are sent to the LoadRunner output window or Application Management agent log file. Example See Also Java Language String lr. Page 82 of 337 lr_get_master_host_name Returns the name of the Controller host. This allows you to determine which options are set. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_host_name Return Values Parameterization char *lr_get_host_name ( ). Example See Also Java Syntax Visual Basic function lr.get_host_name ( ). C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_master_host_name Return Values Parameterization char *lr_get_master_host_name ( ). you can perform a bitwise AND operation. Example See Also Java Language String lr. Example See Also Java Syntax Visual Basic function lr.get_master_host_name ( ).get_master_host_name ( ) as String Example See Also Visual Basic Syntax The lr_get_master_host_name function returns the name of the machine running the Controller . To evaluate the returned value. Example See Also lr_get_transaction_status returns the current status of a transaction. This function returns the duration including Wasted Time. Example See Also Visual Basic function lr. lr_get_transaction_duration returns values greater than zero only for open transactions. it cannot report the final transaction status. transaction_name The name of the transaction. transaction A string indicating the name of a transaction. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_think_time Return Values Parameterization double lr_get_transaction_think_time (const char *transaction). Therefore. you can prevent unnecessary activity. which is made up of a number of steps. use the Transaction Functions. You use this function to determine the total transaction time before the transaction has ended. Since lr_get_transaction_status can only return the status of an open transaction. Example See Also Visual Basic . Page 84 of 337 lr_get_transaction_status Returns the current status of a transaction. the value may be slightly greater than the duration reported for the function when closed with lr_end_transaction. To determine other transaction statistics. This function can be useful when a transaction. lr_get_transaction_status cannot be invoked after lr_end_transaction. By checking the status and terminating the Vuser. such as think time and wasted time.get_transaction_duration ( String transaction ) as double Example See Also Visual Basic Syntax The lr_get_transaction_duration function returns the duration in seconds of the specified transaction to this point. 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_status Return Values Parameterization int lr_get_transaction_status ( const char *transaction_name ) .double lr_get_transaction_duration (const char *transaction). can fail at various points. The difference between this function and lr_get_transaction_duration is that here you specify a transaction instance by its handle. such as think time and wasted time. use the appropriate Transaction Functions. you specify an independent transaction by its name. transaction The transaction name . Page 86 of 337 lr_get_transaction_wasted_time C Language Return Values Parameterization Returns the wasted time of a transaction by its name. Use this function to determine the total transaction time before the transaction has ended. To determine other transaction statistics. . HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_transaction_wasted_time double lr_get_transaction_wasted_time (const char *transaction). Page 87 of 337 lr_get_trans_instance_duration Returns the duration of a transaction instance. With lr_get_transaction_duration. It returns values greater than zero only for open transactions.function lr. such as think time and wasted time. transaction The name of the transaction. The trans_handle is the return value of a call to lr_start_transaction_instance . 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. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_duration Return Values Parameterization double lr_get_trans_instance_duration (long trans_handle). To determine other transaction statistics. use the appropriate Transaction Functions.get_transaction_think_time ( String transaction ) as double Example See Also Visual Basic Syntax The lr_get_transaction_think_time function returns the think time of the specified transaction until this point. Example See Also The lr_get_trans_instance_duration function returns the duration of an open transaction instance in seconds until this point. which is made up of a number of steps. This function can be useful when a transaction instance. The difference between this function and lr_get_transaction_think_time is that here you specify a transaction instance by its handle. Page 88 of 337 lr_get_trans_instance_status Returns the current status of a transaction instance. such as think time and wasted time. Example See Also lr_get_trans_instance_status returns the current status of a transaction instance. can fail at various points of its execution. transaction_handle The name of the transaction. you can prevent unnecessary activity. The trans_handle is the handle returned by the call to lr_start_transaction_instance that created the instance. use the appropriate Transaction Functions. Page 89 of 337 lr_get_trans_instance_think_time Returns the think time of a transaction instance specified by its handle.lr_get_trans_instance_duration returns values greater than zero only for open transactions. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_status Return Values Parameterization int lr_get_trans_instance_status ( long transaction_handle ) . The lr_get_trans_instance_think_time function returns values greater than zero only for open . trans_handle A transaction handle. lr_get_trans_instance_status cannot be invoked after lr_end_transaction_instance . Example See Also The lr_get_trans_instance_think_time function returns the think time of the specified transaction until this point. To determine other transaction statistics. you specify an independent transaction by its name. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_think_time Return Values Parameterization double lr_get_trans_instance_think_time (long trans_handle). The transaction_handle is the handle returned by the call to lr_start_transaction_instance that created the instance. It cannot report the final transaction instance status. With lr_get_transaction_think_time. By checking the status and terminating the Vuser. you specify an independent transaction by its name.transactions. trans_handle A transaction handle. such as think time and wasted time. When performing IP spoofing. With lr_get_transaction_wasted_time. The difference between this function and lr_get_transaction_wasted_time is that here you specify a transaction instance by its handle. Page 90 of 337 lr_get_trans_instance_wasted_time Returns the wasted time of a transaction instance. . Example See Also The lr_get_trans_instance_wasted_time function returns the Wasted Time of the specified transaction until this point. each Vuser can use a different address. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_trans_instance_wasted_time Return Values Parameterization double lr_get_trans_instance_wasted_time (long trans_handle). The lr_get_trans_instance_think_time function returns values greater than zero only for open transactions. such as think time and wasted time. Example See Also Visual Basic function lr. use the appropriate Transaction Functions. To determine other transaction statistics. trans_handle A transaction handle. use the appropriate Transaction Functions. This function allows you to determine the current Vuser's IP address. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_get_vuser_ip Return Values Parameterization char *lr_get_vuser_ip( ). Page 91 of 337 lr_get_vuser_ip Returns the IP address of a Vuser. The trans_handle is the handle returned by the call to lr_start_transaction_instance that created the instance.get_vuser_ip() as String Example See Also Visual Basic Syntax The lr_get_vuser_ip function returns the IP address of a Vuser. To determine other transaction statistics. The lr_load_dll function uses the same search rules as dlopen. On Windows platforms..). see the man pages for dlopen or its equivalent. if you do not specify a path. lr_load_library searches for the DLL using the standard sequence used by the C++ function. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_log_message Return Values Parameterization int lr_log_message (const char *format. Example See Also Java Language int lr. you can call any function defined in the DLL. Page 93 of 337 lr_log_message C Language Sends a message to the Application Management agent log file or the LoadRunner Vuser log. You can avoid overloading the network by using this function to send messages to the log file rather . and not to the output window. Once you load the DLL.log_message ( ByVal message as String ) as Integer Example See Also Visual Basic Syntax The lr_log_message function sends a message to the Vuser or agent log file (depending on the application). LoadLibrary .expn.. you can set the LD_LIBRARY_PATH environment variable (or the platform equivalent). Example See Also Java Syntax Visual Basic function lr. lr_get_vuser_ip returns that IP. On UNIX platforms. Page 92 of 337 lr_load_dll C Language Loads an external DLL. You can specify a full path for the DLL. library_name The name of a DLL (Windows) or shared object (UNIX).If the IP was set with the web_set_sockets_option function using the IP_ADDRESS_BY_INDEX option. exp1. You can use this function for debugging by sending error or other informational messages to the log file. exp2. without having to declare it.log_message ( String message ). 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. For more information.. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_load_dll Return Values Parameterization int lr_load_dll (const char *library_name ). message ( String message ).txt.expn. exp2. and select Always send messages. If you select Send messages only when an error occurs. Use lr_log_message instead of this function to send the message only to the log file. statement Output lr_log_message("a message") a message lr_output_message("message"). expn C Language The expressions (variables) to be formatted and printed. To send a message to the output file. exp2. In the Vuser Execution log. exp1.). exp1.than sending messages to the Output window (with lr_error_message or lr_output_message). format C Language A formatted string to send to the log file. To issue a message with those details. This conserves the network and controller resources required for sending messages to the output... Example See Also Java Language int lr. Action(4): a message Page 94 of 337 lr_message C Language Sends a message to the log and output window..message ( ByVal message as String ) as Integer Example See Also Visual Basic Syntax The lr_message function sends a message to the log file and output window. this function does not list the location and line number from where the message was issued. When run in VuGen. use lr_output_message. . In a standalone program such as VuGen. Use the standard Message Formatting that is available for printf to set the format for the expressions you want to print.. lr_log_message sends the message to the viewer and output.. See VB String Arguments and Java String Arguments. there is no output from this function. message Object oriented languages A string containing the message to send to the log.txt. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_message Return Values Parameterization int lr_message (const char *format. you must enable logging in the run-time settings. enclose it with quotation marks. Example See Also Java Syntax Visual Basic function lr. If it is a literal string. the output file is output. If you select Send messages only when an error occurs.missing () as Variant. use the class or keyword MISSING. output windows. Use the standard Message Formatting that are available for printf to set the format for the expressions you want to print. you must enable logging in the run-time settings. enclose it with quotation marks. exp n C Language The expressions (variables) to be formatted and printed. exp 2 . VB. and other test report summaries.missing Java Script Returns an Variant whose value is Missing. Example See Also Use lr.empty to pass an Missing variant to a function that requires a Variant argument. exp 1 . . this function does not list the location and line number from where the message was issued.. statement Output lr_message("a message") a message lr_output_message("a message"). See VB String Arguments and Java String Arguments. HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr.NET or C#. Example See Also VB Script Function lr. In the log file. there is no output from this function. To issue a message with those details. message Object oriented A string containing the message to send to the Output window. In Visual Basic. Page 96 of 337 lr_output_message C Language Sends a message to log files. and select Always send messages. format C Language A formatted string.missing (). use lr_output_message.missing Return Values Parameterization Variant lr.To send a message to the output file. Action(4): a message Page 95 of 337 lr.) > lr. If it is a literal string.. there is no output from this function. See VB String Arguments and Java String Arguments. If you select Send messages only when an error occurs. If it is a literal string.. the output file is output. exp n C Language The expressions (variables) to be formatted and printed. When a script is run in VuGen..output_message ( ByVal message as String ) as Integer Example See Also Visual Basic Syntax The lr_output_message function sends a message with the script section and line number to output windows (such as the LoadRunner output window).. To send an error message to the LoadRunner output window or Application Management agent log. For details regarding the output for each product. To send a message to the Vuser execution log or Application Management Web site. exp1. To issue a message without including the location details. format C Language A formatted string. To send a message to the output file.. It is not recommended that you send a message to the output window or agent log in the middle of a transaction. log files (such as the Vugen log file and the Application Management Web site and agent log file). enclose it with quotation marks. as it will lengthen the execution time. but not to the Output window. exp 1 .output_message ( String message ). message Object Oriented A string containing the message to send to the Output window. use lr_message. exp 2 . you must enable logging in the run-time settings. see the products' user guides. exp2.). and other test report summaries.txt. use lr_log_message.. Use the standard Message Formatting that is available for printf to set the format for the expressions you want to print. and select Always send messages. use the lr_error_message function. Example See Also Java Language int lr. .HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_output_message Return Values Parameterization int lr_output_message (const char *format.expn. Example See Also Java Syntax Visual Basic function lr. paramArrayName The name of the parameter array from which to return the value. Actions. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_paramarr_len Return Values Parameterization int lr_paramarr_len (const char * paramArrayName).g.statement Output lr. The value is returned from the parameter at a position chosen randomly by LoadRunner. . Example See Also lr_paramarr_idx returns a string containing the value of the parameter at the specified position in a parameter array.log_message("a message") a message lr. char *str = NULL. unsigned int index). the return value is the concatenation of "{". lr_output_message("%s". index. "_". for example. paramArrayName. str). If the parameter does not exist.java (4): a message Page 97 of 337 Note: Do not send null pointers as arguments to string formats e. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_paramarr_idx Return Values Parameterization char * lr_paramarr_idx ( const char * paramArrayName. and "}". Page 99 of 337 lr_paramarr_len C Language Returns the number of elements in a parameter array. "{myParam_4}". index The one-based position of the parameter in the array. Example See Also lr_paramarr_len returns the number of elements in a parameter array. Example See Also lr_paramarr_random returns a string containing the value of the parameter in a parameter array. paramArrayName The name of the parameter array.output_message("a message"). Page 98 of 337 lr_paramarr_idx C Language Returns the value of the parameter at a specified location in a 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 Return Values Parameterization char * lr_paramarr_random (const char * paramArrayName). l r _save_st r i ng( buf . and stores the incremented value as a null terminated string in destination_param. const char *source_param). %hhi. %hhf . When destination_param exists. ] ). For protocols that have only string parameters. 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. "%d" . %hd. Example See Also The lr_param_increment function retrieves the value of source_param. source_param must be initialized with an integer value prior to calling lr_param_increment. "next _modnum" ) . "{modi f i cat i on_num}" ) . . HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_increment int lr_param_increment (const char *destination_param. This function is useful only in protocols that have a numerical parameter type. %lld.. its value is overwritten. %lli. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_sprintf Return Values Parameterization int lr_param_sprintf ( const char * paramName. lr_param_increment can be used: l r _par am_i nc r ement ( "next _modnum" . Page 101 of 337 lr_param_increment C Language Return Values Parameterization Increments the value of a numerical parameter. %hhe. %llf. const char * format [. %hhd. i +1) . %ld. increments its value by one. %llu. For example: i = at oi ( l r _eval _st r i ng( "{modi f i cat i on_num}" ) ) . These formatting characters are not supported: %E. spr i nt f ( buf . When it doesn't exist.. increment with C functions. %hhu . For protocols that have a numerical parameter. and %lle.paramArrayName The name of the parameter array. the parameter is created dynamically. source_param's value should include only single-byte digit characters with an optional sign or leading zeros.args . 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 C Language Writes formatted output to a parameter. The value of source_param is restricted to the maximum value of a long integer minus 1. Page 104 of 337 lr_peek_events Checks for events. Example See Also Java Syntax Visual Basic sub lr. Your cannot use standard parameterization with this function. Page 103 of 337 lr_param_unique C Language Generates a unique string and assigns it to a parameter. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_param_unique Return Values Parameterization int lr_param_unique (const char * paramName). Java and Java Script HP LoadRunner Online Function Reference > Utility Functions: Java Language (lr. Example See Also Java Language void lr. Scripts written in C language perform this check internally.) > lr. paramName The target parameter to which the string is written. Page 105 of 337 lr.paramName The target parameter to which the string is written. there is no need to use the lr_peek_events function. Therefore. Scripts written in Java or Visual Basic do not perform this check internally.read_xml Returns the contents of an XML file as a string. The string contains no spaces. Example See Also lr_param_unique generates a string of format: <GroupName><UserID><CurrentTime>.peek_events ( ). Therefore.lr. format One or more formatting characters.read_xml String.peek_events ( ) Example See Also Visual Basic Syntax The lr_peek_events function suspends the Vuser script run and checks for events before resuming.read_xml (String file_name). insert this function into your Vuser script at the point at which you want the Vuser to pause. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_peek_events Return Values Parameterization void lr_peek_events ( ). args Optional print arguments. Example See Also . The file must exist in the data\SerializedObjects directory under the script directory. rendezvous_name The name of the rendezvous. Page 106 of 337 lr_rendezvous Creates a rendezvous point in the Vuser script.rendezvous ( ByVal rendezvous_name as String ) as Integer Example See Also Visual Basic Syntax The lr_rendezvous function creates a rendezvous point in a Vuser script. it returns null. . rendezvous_name The name of the rendezvous. Page 107 of 337 lr_rendezvous_ex Creates a rendezvous point in the Vuser script. The difference between this function and lr_rendezvous is that lr_rendezvous returns only LR_PASS or LR_FAIL. When this statement is executed. Example See Also Java Language int lr.The lr. The timeout is set in the scenario policy in the Controller. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_rendezvous Return Values Parameterization int lr_rendezvous (const char *rendezvous_name). This function can only be used in action section. The difference between lr_rendezvous and lr_rendezvous_ex is that lr_rendezvous always returns zero. the Vuser program stops and waits for permission from LoadRunner to continue. and not in vuser_init or vuser_end. Example See Also Java Syntax Visual Basic function lr. file_name The file to read and return as a string. The default timeout is 30 sec. and not in vuser_init or vuser_end. This function can only be used in an action section.rendezvous ( String rendezvous_name ). If the call fails. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_rendezvous_ex Return Values Parameterization int lr_rendezvous_ex (const char *rendezvous_name). When this statement is executed. Example See Also The lr_rendezvous_ex function creates a rendezvous point in a Vuser script. the Vusers stop and wait for permission from LoadRunner to continue.read_xml function returns the contents of the specified file as a String. the final results when the test is analyzed will reflect the total values. the "get" functions return all data since the start of the transaction. including the periods in between the transaction stop and resume. On PC platforms. Furthermore. LR_REND_NOT_FOUND 3 The rendezvous was not found. see lr_start_sub_transaction. and lr_set_transaction. For more general ways of reporting partial transaction durations. until this function is called. LR_REND_DISABLED 2 The rendezvous was disabled from the Controller. If lr_resume_transaction is not called. statistics returned by the "get" Transaction Functions reflect only the data up to that call. Example See Also Visual Basic Sub lr. On UNIX platforms. however. 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_VUSER_NOT_ MEMBER 4 Vuser was not defined in the rendezvous. LR_REND_BY_USER 6 The rendezvous was released by the user. After a call to lr_stop_transaction. Data collection. After the call to lr_resume_transaction. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_resume_transaction void lr_resume_transaction (const char *transaction_name). the function returns one of the values described in the table. LR_REND_VUSER_DISABLED 5 Vuser was disabled for the rendezvous.Page 108 of 337 Rendezvous Return Values The return values of the lr_rendezvous function are defined in the Lrun. LR_REND_TIMEOUT 1 Vuser was released after the timeout value was reached. the "get" functions and the final results reflect only the . The lr_resume_transaction function resumes the reporting of transaction data within the script that was suspended by lr_stop_transaction. is not interrupted.resume_transaction ( String transaction_name ) Example See Also Visual Basic Syntax This function is retained for backward compatibility. Page 109 of 337 lr_resume_transaction C Language Return Values Parameterization Resumes reporting transaction data within a script.h file. this technique does not apply. The parent_handle is the value returned from the call to lr_start_transaction_instance that created the instance. 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. is not interrupted. transaction_name The name of the transaction. until this function is called. call lr_resume_transaction only if your condition is met. this technique does not apply. however. the data in analysis will reflect both the tests where the condition for lr_resume_transaction is met. 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 Return Values Parameterization void lr_resume_transaction_instance ( long trans_handle ). To accomplish this. Furthermore.duration from the transaction start to the lr_stop_transaction call. the final results reflect the statistics only until the call to lr_stop_transaction_instance. see lr_start_sub_transaction. Note that you will not be able to differentiate in analysis between iterations when . For other ways of recording durations conditionally. Thus. After the call to lr_resume_transaction_instance. lr_stop_transaction and lr_resume_transaction can be used conditionally to collect information either about an entire transaction. If lr_resume_transaction_instance is not called. If you need to differentiate between occurrences where the lr_resume_transaction condition is met and those where it is not in the analysis data. or only the beginning. or all of the transaction. including the periods in between the transaction instance stop and resume. Note: When data is collected this way. Data collection. lr_stop_transaction_instance and lr_resume_transaction_instance can be used to conditionally collect information about either the beginning. After a call to lr_stop_transaction_instance. statistics returned by the "get" Transaction Functions reflect only the data up to that call. and lr_set_transaction. and the tests where it is not. the "get" functions return all data since the start of the transaction. If the section you may wish to exclude ends before the end of the transaction. the final results when the test is analyzed will reflect the total values. depending on the definitions in your computer's locale. ONE_MIN.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.h. int offset. VB Script (lr. lr_set_transaction.save_double function saves value to parameter param_name. which is defined in lrun. offset Offset from the current date and time. "%d%b%y" would return 29JAN97. Visual Basic and VB Script Return Values Parameterization HP LoadRunner Online Function Reference > Utility Functions: VB. It creates the parameter if it does not exist. value as Double ) Example See Also Visual Basic Syntax The lr.) > lr. TIME_NOW + ONE_HOUR name The name of the parameter to store the date/time information. TIME_NOW.save_double Saves a double value as a parameter. Page 112 of 337 lr. Example See Also The lr_save_datetime function saves the current date and time. "The current month is %b" would return The current month is JAN. ONE_DAY. For example. ONE_HOUR. You can use theDatetime Format Codes to build a format with any combination of strings and codes. format The format of the retrieved date/time information. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_datetime Return Values Parameterization void lr_save_datetime(const char *format. For example. see lr_start_sub_transaction.lr_stop_transaction_instance was called and iterations where it was not. using the constants: DATE_NOW. The format can be a format defined in an included header file. For more flexible ways recording transaction times conditionally. such as DATE_FM. const char *name). param_name The parameter in which to save the value value A numeric value Page 113 of 337 .save_double Sub lr. The resulting string will be truncated once it reaches MAX_DATETIME_LEN characters. or the date and time with the specified offset into a parameter.save_double (ByVal param_name as String. value The integer value to assign to the parameter. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_int Return Values Parameterization int lr_save_int ( int value. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_searched_string Return Values Parameterization int lr_save_searched_string (const char *buffer. It creates the parameter if it does not exist. Example See Also The lr_save_int function converts an integer to a string and saves the string in a parameter.) > lr.lr_save_int . value as long ) Example See Also Visual Basic Syntax The lr.save_long Sub lr. const char *search_string.save_long function saves value to parameter param_name. If the parameter does not exist. and has length string_len. Saves an integer to a parameter. it is created. int offset. const char *parm_name ).save_long (ByVal param_name as String. long buf_size. Page 114 of 337 lr. param_name The name of the parameter. Example See Also The lr_save_searched_string function searches for string search_string inside string or character array buffer. where n is occurrence plus 1. 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. For example: . const char *param_name). unsigned int string_len. The substring to be saved starts at offset after the end of the nth occurrence of search_string. VB Script (lr. Visual Basic and VB Script Return Values Parameterization HP LoadRunner Online Function Reference > Utility Functions: VB. unsigned int occurrence.save_long Saves a long value as a parameter. and finds the nth occurrence of search_string. buf_size The buffer size. i n par amet er Fannys_br ot her . For example. Page 116 of 337 lr_save_string Saves a null-terminated string to a parameter. Af t er t he cal l . The search_string cannot contain null characters. occurrence The occurrence number of the search_string (0-based count). use the lr_eval_string function. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_string Return Values Parameterization int lr_save_string (const char *param_value. " abc" . Use the lr_save_string function to save strings from character arrays. Example See Also Java Language int lr. set occurrence to 1. offset The number of characters to skip after the end of the search string occurrence. . param_value The value to assign to the parameter. l r _s ave_s ear c hed_s t r i ng( cBuf f . . / / . To determine the value of the parameter. ByVal param_value as String ) as Integer Example See Also Visual Basic Syntax The lr_save_string function assigns the specified null-terminated string to a parameter. " Fannys_br ot her " ) . .char cBuf f [ ] = " abc Emma Woodhouse abc El i zabet h Bennet abc Wi l l i am Pr i ce" . / / Put t he next f our char act er s. . t he cont ent of par amet er Fannys_br ot her i s "Wi l l " . String param_name). buffer The STRING or CARRAY buffer. part of whose contents you want to save. 2. string_len The number of characters to save. and you want the second occurrence. parm_name Parameter name to be used in subsequent lr statements to refer to the saved information.save_string ( String param_value . . st r l en( cBuf f ) .save_string ( ByVal param_name as String. / / Sear ch f or t hi r d occur r ence of " abc" 1. Example See Also Java Syntax Visual Basic function lr. / / Ski p t he space af t er " abc" 4. Use lr_save_searched_string only when you need to save a portion of a character array relative to a string occurrence. search_string The string to search for in the buffer. Name is enclosed in double-quotes. This function is useful in correlating queries. but the buffer can contain null characters. if the search_string occurs three times. const char *param_name). currently 0.param_name The name of the parameter. To determine the value of the parameter. The messages are sent to the Application Management agent log or the LoadRunner Vuser output. Example See Also The lr_save_var function assigns the specified variable length string to a parameter. Page 117 of 337 lr_save_var C Language Saves a variable length string to a parameter.set_debug_message ( int message_level. Page 118 of 337 lr_set_debug_message Sets the message level for the script execution. The value can be changed from the current Run-time Settings value. value_len The length of the value in bytes. unsigned int on_off). Example See Also Java Language int lr. const char *param_name). By setting a message level. if the script's current message level in . options A parameter option. For example. Example See Also Java Syntax Visual Basic function lr. unsigned long const options. The setting is enabled by passing LR_SWITCH_ON as on_off . ByVal on_off as Integer ) as Integer Example See Also Visual Basic Syntax The lr_set_debug_message function sets the debug message level. and disabled with LR_SWITCH_OFF. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_save_var Return Values Parameterization int lr_save_var (const char *param_value. unsigned long const value_len. param_value The value to assign to a parameter. This function is useful in correlating queries. int on_off ). Message levels are generally set in the script's Run-time Settings dialog box. for the script execution. you determine which information is sent. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_debug_message Return Values Parameterization int lr_set_debug_message (unsigned int message_level. param_name The name of the parameter. message_lvl.set_debug_message ( ByVal message_level as Integer. use the lr_eval_string function. or subsettings. set _debug_message ( l r . To set one of these sub-settings you can use logical Or's in your message_level argument. or where you may or may not want to create a transaction. int status). MSG_CLASS_EXTENDED_LOG. the value can be increased to "Extended log" (LR_MSG_CLASS_EXTENDED_LOG): l r _set _debug_message( LR_MSG_CLASS_EXTENDED_LOG. double duration. and Full Trace. int status). depending on conditions that are known . Use LR_SWITCH_DEFAULT with a single message_level argument. Parameter Substitution. Use one of the On-Off Constants. Example See Also Java Language int lr. on_off A switch to activate or deactivate a specific message level setting. Example See Also Java Syntax Visual Basic Function lr. int status) as integer Example See Also Visual Basic Syntax The lr_set_transaction function creates a transaction. of the Extended log setting. The message levels Result Data. return to the disabled state by setting the debug level to zero (0) and activating the option using the lr. double duration.SWITCH_ON switch as the second parameter. set the message level to another level. are specific details. Page 119 of 337 Page 120 of 337 lr_set_transaction C Language Creates a completed transaction. double duration. After enabling the logging. Use it where the business process you want to capture in a transaction does not consist of sequential steps. For example: l r . It does not work with ORed message_level settings. l r . message_level One of the Message Log Run-Time Settings.set_transaction( String name. and status in a single call. 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.set_transaction( String name.the Run-time Settings is set at "Brief" mode. LR_SWI TCH_OFF) To enable logging that is disabled in the Run-time Settings. SWI TCH_ON) . its duration. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction Return Values Parameterization int lr_set_transaction(const char *name. LR_SWI TCH_ON) and later decreased to "Brief" once again: l r _set _debug_message( LR_MSG_CLASS_EXTENDED_LOG. If this status is LR_AUTO the value is automatically assigned. 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. The handle was returned by lr_start_transaction_instance . One of theTransaction Status constants for pass. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction_instance_status Return Values Parameterization int lr_set_transaction_instance_status (int status. use the native language time functions. In analysis. Therefore. Example See Also The lr_set_transaction_instance_status function sets the status of the open transaction with the transaction handle trans_handle. long trans_handle).) in a transaction name. To create a transaction for non-sequential steps. this value is LR_PASS signifying a successful transaction. The period character delimits transactions and sub-transactions. lr_set_transaction creates and closes the transaction. status The transaction completion status. This transaction's lr_end_transaction_instance statement must use automatic status assignment by passing a Transaction Status of auto as its status parameter. no functions that work only on open transactions are applicable. fail. lr_set_transaction_instance_status changes this default value to status.only during the test. or stop. For more information on transaction instances. By default. A transaction's status is defined in the status parameter of lr_end_transaction_instance. capture the duration of each series of steps that participate in the business process. Note: Do not use the period character (. Name A name for the transaction. . Sum the durations and create the transaction with lr_set_transaction. duration Transaction duration in seconds. For other languages. To capture durations in C language scripts. The auto status is not applicable. see lr_start_transaction_instance. use lr_start_timer and lr_end_timer. a transaction name with a period will be interpreted as two transactions. Page 121 of 337 lr_set_transaction_instance_status Sets the status of a transaction instance. lr_set_transaction_status changes this default value to status. By default. By default. This transaction's lr_end_transaction statement must use automatic status assignment by passing LR_AUTO as its status parameter.set_transaction_status ( int status). this value is LR_PASS. or stop. fail. signifying a successful transaction. status One of theTransaction Status constants for pass. lr_set_transaction_status_by_name changes this default value to status.status One of theTransaction Status constants for pass. fail. A transaction's status is defined in the status parameter of lr_end_transaction. 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 Return Values Parameterization int lr_set_transaction_status_by_name (int status. this value is LR_PASS. The auto status is not applicable. the value is automatically assigned. If this status is LR_AUTO. fail. Example See Also Java Syntax The lr_set_transaction_status function sets the status of those transactions currently open which have LR_AUTO in their lr_end_transaction statement. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_set_transaction_status int lr_set_transaction_status (int status). const char *trans_name). or stop. trans_name The transaction name . status One of theTransaction Status constants for pass. The auto status is not applicable. or stop. If this status is LR_AUTO. signifying a successful transaction. A transaction's status is defined in the status parameter of lr_end_transaction. trans_handle The handle to a transaction instance Page 122 of 337 lr_set_transaction_status C Language Return Values Parameterization Sets the default end status of open transactions. Example See Also Java Language int lr. Example See Also The lr_set_transaction_status_by_name function sets the default status of the open transaction with name trans_name. the value is automatically assigned. The auto status is not applicable. Page 124 of 337 lr_start_sub_transaction Starts a sub-transaction specified by its parent's name. use lr_end_sub_transaction. The duration of a transaction or sub-transaction is the sum of the durations of all steps between its start and end. To mark the end of the sub-transaction. 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. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_sub_transaction Return Values Parameterization int lr_start_sub_transaction (const char *sub_transaction. A subtransaction may also be a parent to a smaller sub–transaction. Note: Do not use the period character (. Example See Also Java Syntax Visual Basic Function lr. String parent_transaction). In analysis. Sub-transactions are used for isolating parts of a business process. You insert these functions immediately before and after the sub-transaction actions. For example. Example See Also Java Language int lr. const char *parent_transaction). including the steps that are included in sub-transactions.) in a transaction or sub-transaction name.start_sub_transaction (String sub_transaction. Multiple sub-transactions can be nested within a parent transaction." The transaction "purchases" is the parent transaction and "electrical_purchases" the sub-transaction. a sub-transaction "electrical_purchases" may be nested within the larger transaction "purchases. 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 .start_sub_transaction (String sub_transaction. String parent_transaction) as Integer Example See Also Visual Basic Syntax The lr_start_sub_transaction function marks the beginning of a sub-transaction. a transaction name with a period will be interpreted as two transactions. The period character delimits transactions and sub-transactions. Example See Also lr_start_timer starts a timer that calculates the passage of time in seconds.start_transaction ( ByVal transaction_name as String ) as Integer Example See Also Visual Basic Syntax The lr_start_transaction function marks the beginning of a transaction. The period character delimits transactions and sub-transactions. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_transaction_instance Return Values Parameterization . C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_timer Return Values Parameterization merc_timer_handle_t lr_start_timer (). These functions are inserted immediately before and after the transaction. use the lr_start_transaction and lr_end_transaction functions.) in a transaction or sub-transaction name. a transaction name with a period will be interpreted as two transactions. Note: Do not use the period character (. Page 126 of 337 lr_start_transaction Marks the beginning of a transaction. To indicate a transaction to be analyzed. In analysis. The maximum resolution is a microsecond. Transactions can be nested. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_start_transaction Return Values Parameterization int lr_start_transaction ( const char *transaction_name ). transaction_name The name of the transaction. Example See Also Java Syntax Visual Basic function lr. The resolution depends on the run-time environment. Page 127 of 337 lr_start_transaction_instance Starts a transaction instance. lr_start_timer returns a handle to the timer. Pass the handle to lr_end_timer to stop the timer. Example See Also Java Language int lr.Starts a timer. but each lr_start_transaction statement must be associated with an lr_end_transaction statement or it will be interpreted as an illegal command.start_transaction ( String transaction_name ). and lr_set_transaction. By passing the handle of a parent transaction instance. a transaction name with a period will be interpreted as two transactions. handle The parent transaction's handle. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_stop_transaction double lr_stop_transaction (const char *transaction_name). Instances are identified by their handle which distinguishes them from other instances of the same transaction. Example See Also Visual Basic Function lr. Use transaction instances when the same transaction is required to be performed under different circumstances and an analysis of each circumstance is required. Example See Also The lr_start_transaction_instance function marks the beginning of a transaction instance. see lr_start_sub_transaction. For more general ways of reporting partial transaction durations. until lr_resume_transaction is called.long lr_start_transaction_instance ( const char *transaction_name. A value of 0 instructs VuGen to create a new parent transaction. the new instance will be considered a subtransaction instance of the parent. long handle). The function returns the handle of the transaction instance which identifies the instance. statistics returned by the "get" Transaction Functions reflect only the data up to the call. Page 128 of 337 lr_stop_transaction C Language Return Values Parameterization Freezes reporting of transaction data.) in a transaction or sub-transaction name. The period character delimits transactions and sub-transactions.stop_transaction ( String transaction_name ) as Double Example See Also Visual Basic Syntax This function is retained for backward compatibility. In analysis. transaction_name The name of the transaction. The specified transaction must have . This function enables multiple instances of a transaction to be created. A transaction instance is an occurrence of a transaction with transaction_name. Note: Do not use the period character (. For more information on sub-transactions. Pass zero as the handle if there is no parent. 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. After a call to lr_stop_transaction. see lr_start_sub_transaction. is not interrupted. and the tests where it is not. the final results reflect the statistics only until the call to lr_stop_transaction_instance. the "get" functions and the final results reflect only the duration from the transaction start to the lr_stop_transaction call. The specified transaction instance must have been opened with lr_start_transaction_instance.been opened with lr_start_transaction. or only the beginning. the "get" functions return all data since the start of the transaction instance. statistics returned by the "get" Transaction Functions reflect only the data up to the call. Note: When data is collected this way. call lr_resume_transaction only if your condition is met. including the periods in between the transaction stop and resume. transaction_name The name of an open transaction. If you need to differentiate between occurrences where the lr_resume_transaction condition is met and those where it is not in the analysis data. this technique does not apply. If the section you may wish to exclude ends before the end of the transaction. the data in analysis will reflect both the tests where the condition for lr_resume_transaction is met. until lr_resume_transaction_instance is called. Data collection. Example See Also After a call to lr_stop_transaction_instance. After the call to lr_resume_transaction_instance. . lr_stop_transaction and lr_resume_transaction can be used conditionally to collect information either about an entire transaction. the final results when the test is analyzed will reflect the total values. is not interrupted. including the periods in between the transaction stop and resume. Furthermore. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_stop_transaction_instance double lr_stop_transaction_instance (long parent_handle). Data collection. this technique does not apply. however. To accomplish this. Furthermore. the "get" functions return all data since the start of the transaction. If lr_resume_transaction is not called. however. After the call to lr_resume_transaction. the final results when the test is analyzed will reflect the total values. Thus. If lr_resume_transaction_instance is not called. Page 129 of 337 lr_stop_transaction_instance C Language Return Values Parameterization Freezes reporting statistics for a transaction instance specified by its handle. or all of the transaction. double value). Page 131 of 337 lr_user_data_point Records a user-defined data sample. thinkTime The length of the pause.The parent_handle is the value returned from the call to lr_start_transaction_instance that created the instance. in seconds. see lr_start_sub_transaction.think_time ( ByVal thinkTime as Double ) Example See Also Visual Basic Syntax lr_think_time allows you to pause test execution during a run. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point Return Values Parameterization int lr_user_data_point (const char *sample_name. Page 130 of 337 lr_think_time C Language Pauses execution between commands in a script. lr_stop_transaction_instance returns the duration of the instance in seconds.user_data_point ( ByVal sample_name as String. parent_handle A unique transaction handle.user_data_point ( String sample_name. lr_set_transaction. ByVal value as double ) as Integer .think_time ( double thinkTime ). Example See Also Java Syntax Visual Basic sub lr. 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. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_think_time Return Values Parameterization void lr_think_time (double thinkTime).and lr_start_timer. lr_stop_transaction_instance and lr_resume_transaction_instance can be used to conditionally collect information about either the beginning. Example See Also Java Language int lr. Example See Also Java Syntax Visual Basic function lr. the time a real user pauses to think between actions. Example See Also Java Language void lr. This is especially useful in simulating think time. double value ). the prefixes are case-sensitive. 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. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_user_data_point_ex Return Values Parameterization int lr_user_data_point_ex ( const char *sample_name. int log_flag).txt You may want to write the data point conditionally according to how important the data to be logged is. for example "HTTP_BT". 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. The time that the sample is recorded automatically. use this function to record the sample name and the value. After the execution. Page 132 of 337 lr_user_data_point_ex Records a user-defined data sample and enables logging option. therefore "http_BT" is a valid sample_name. the output is output. 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. It can either be part of a Standard level when only the most important information is logged or an Extended level. Note: The following prefixes in sample_name are reserved: HTTP NON_HTTP RETRY mic_ stream_ mms_ A data point with any of these prefixes. sample_name The data point name. lr_user_data_point_ex enables you to write a data point to the Vuser log file. However. When run in VuGen. Logging means writing data to a file. will not appear on the graph. double value. when fuller logging is required.Example See Also Visual Basic Syntax The lr_user_data_point function allows you to record your own data for analysis. value The value to record. If log_flag is DP_FLAGS_STANDARD_LOG then it will be logged . you can use the User Defined Data Points graph to analyze the results. Each time you want to record a point. long transaction_handle). value The value to record. sample_name A string indicating the name of the sample type. Logging means writing data to a file. the output is output. When run in VuGen.only if the Standard setting is active. 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. For details on transaction instances.txt . Page 134 of 337 lr_user_data_point_instance_ex C Language Return Values Parameterization Records a user-defined data sample and correlates it to a transaction instance. long transaction_handle. This function is intended for use with applications integrated with LoadRunner that use transaction instances. 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. parent_handle A transaction instance identifier with which to associate the data_point. lr_user_data_point_instance_ex enables you to write a data point to the Vuser log file. value The value to record. see lr_start_transaction_instance. int log_flag). DP_FLAGS_NO_LOG indicates that this data point is never written to a log file. 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 C Language Return Values Parameterization Records a user-defined data sample and correlates it to a transaction instance. 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. sample_name A string indicating the name of the sample type. 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. DP_FLAGS_NO_LOG indicates that this data point is never written to a log file. HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_vuser_status_message .vuser_group function returns the name of the Vuser group to which the Vuser belongs.vuser_id function returns the ID of the running Vuser. Page 136 of 337 lr.vuser_group Function lr. VB Script (lr. It can either be part of a Standard level when only the most important information is logged or an Extended level. Visual Basic and VB Script Return Values Parameterization HP LoadRunner Online Function Reference > Utility Functions: VB.) > lr.vuser_id Returns the Vuser ID.vuser_group Returns the name of the Vuser group. parent_handle A transaction instance identifier with which to associate the data_point. sample_name A string indicating the name of the sample type.vuser_id ( ) as Long Example See Also Visual Basic Syntax The lr. 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. Visual Basic and VB Script HP LoadRunner Online Function Reference > Utility Functions: VB.vuser_group ( ) as String Example See Also Visual Basic Syntax The lr. 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. If log_flag is DP_FLAGS_STANDARD_LOG then it will be logged only if the Standard setting is active.) > lr. Page 137 of 337 lr_vuser_status_message C Language Return Values Parameterization Sends a message to the Vuser status area. 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. value The value to record.You may want to write the data point conditionally according to the importance of the data to be logged. VB Script (lr.vuser_id Return Values Parameterization Function lr. int lr_vuser_status_message (const char *format). Example See Also Java Syntax Visual Basic Function lr. replace the parameter name with NULL. the message is sent to output. Page 139 of 337 lr_whoami Returns information about the Vuser executing the script. vuser_id A pointer to an output argument to store the Vuser ID number. You do not have to allocate explicitly in the script. lr_wasted_time allows you to subtract the time wasted on incidental or secondary actions from all open transactions. When run from VuGen. Example See Also Java Language int lr. Example See Also Other languages See lr_set_transaction for an alternative. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_whoami Return Values Parameterization void lr_whoami (int *vuser_id. If you do not want to retrieve one or more of the parameters.vuser_status_message ( String message ). not altered.txt. Page 138 of 337 lr_wasted_time Removes wasted time from all open transactions. sgroup A pointer to an output argument to store the name of the Vuser Group. For more information. It also sends this string to the Vuser log. Memory for the string is allocated automatically.vuser_status_message ( message As String ) as Integer Example See Also Visual Basic Syntax The lr_vuser_status_message function sends a string to the Status area of the Controller. see Wasted Time. Not applicable for products that do not run individual Vusers. . scid A pointer to an output argument to store the Scenario or Session step ID number. char **sgroup. Example See Also The lr_whoami function gets information about the Vuser. wasteTime The time in milliseconds to be removed from all open transactions. C Language HP LoadRunner Online Function Reference > Utility Functions: C Language (LR) > lr_wasted_time Return Values Parameterization void lr_wasted_time (long wasteTime). Note that the sgroup parameter is a pointer to constant data and should only be read. int *scid). the statement: printf("My name is %s%s\n". When this number is preceded by a 0. If precision is greater than fractional part.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. indicates how many characters the field should be padded. 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.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." the second expression (Dent) would have been ignored. The last character of format is a letter code that determines the type of formatting. prints trailing zeros g. The possible letter codes are as follows: Note that a separate formatting specification must be provided for each expression to be printed. "Dent"). 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. "Arthur". One or more format modifiers can appear between the first and last character of the format argument (see below). Without the second "%s.dddddd e+exponent). For example.Page 140 of 337 Message Formatting The first character of the format parameter is always a percent sign (%). The output generated by a particular formatting code can be modified. prints the statement "My name is Arthur Dent" to standard output. 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: . field width A number. the padding occurs with zeros to the left of the printed value.i int decimal number o int unsigned octal number without a leading zero x. by itself or to the left of a decimal point.E double engineering notation (m. MSG_CLASS_ PARAMETERS 4 Full Run-Time Trace LR_MSG_CLASS_ FULL_TRACE lr.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_ RESULT_DATA 2 Parameter Substitution LR_MSG_CLASS_ PARAMETERS lr.MSG_CLASS_ FULL_TRACE 8 Log Level C Language Constants Object Oriented Constants Value Only on error.MSG_CLASS_ BRIEF_LOG 1 Extended Log LR_MSG_CLASS_ EXTENDED_LOG lr.MSG_CLASS_ EXTENDED_LOG 16 Log Level C Language Constants Object Oriented Constants Value Result Data LR_MSG_CLASS_ RESULT_DATA lr.MSG_CLASS_ DISABLE_LOG 0 Brief LR_MSG_CLASS_ BRIEF_LOG lr. Which messages sent on error depends on other settings. LR_MSG_CLASS_ JIT_LOG_ON_ ERROR . They must appear in the following order: The correct order is: RAW_BODY_START. To enable a more simple representation of the raw data.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 Object Oriented Constants Value Turns the setting off. 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). click the Parameterization button in that function.SWITCH_ DEFAULT 2 Page 143 of 337 Parameterization Background For information about the arguments that are available for parameterization.SWITCH_ OFF 0 Turns the setting on. the Raw Body attribute instead enables you to pass a pointer to the binary content. LR_SWITCH_ ON lr. However. The syntax for sending raw body content is a set of 4 arguments to web_custom_request(). LR_SWITCH_ DEFAULT lr.SWITCH_ ON 1 Uses the defaults from the script's cfg file. LR_SWITCH_ OFF lr.lr. . this method requires that content is converted into ASCII text using escape backslashes for non–printable text. LAST) . That is. even when the length is 0. .0 and 8. 1. The Raw Body group cannot be used with the Binary parameter set ("Binary=1"). . The pointer data buffer must not be NULL. "{MyParam}") in the data buffer will not be substituted with the corresponding parameter value..EXIT_VUSER Exit without any condition. " abc" . / * a poi nt er t o t he r aw dat a */ web_cust om_r equest ( "St epName" .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. ur l " . "URL=ht t p: / / some. RAW_BODY_START. 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. 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.a poi nt er t o t he dat a buf f er . and go directly to end action LR_EXIT_ACTION_ AND_CONTINUE lr.EXIT_ACTION_ AND_CONTINUE Stop current action. 3. and go to the next action. The data buffer cannot be parameterized. -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. RAW_BODY_END. any parameter reference (e. and will be used as is.g. RAW_BODY_END The syntax is illustrated in the following example: char *abc= .1. Thi s was t he behavi or bef or e ver si on 8. "Met hod=POST" . LR_EXIT_MAIN_ ITERATION_ . ( i nt ) l engt h. EXIT_VUSER_ AFTER_ACTION Run until the end of the current action and then exit.AUTO LR_STOP lr. 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.EXIT_ITERATION_ AND_CONTINUE Stop current iteration. HP LoadRunner Online Function Reference > Utility Functions: Socket ID Functions > Transaction Status C Constants Object Oriented Constants LR_PASS lr. LR_EXIT_ITERATION_ AND_CONTINUE lr. The status can be read before completion.FAIL LR_AUTO lr.AUTO Page 147 of 337 Transaction Status Transactions complete with one of these statuses. but may change at any time until the transaction completes. only the block iteration will be exited.EXIT_MAIN_ ITERATION_ AND_CONTINUE Stop current global script run iteration. and go to the next iteration.STOP Visual Basic Syntax String Arguments Argument Lists Special Characters . LR_EXIT_VUSER_ AFTER_ACTION lr.PASS LR_FAIL lr.PASS LR_FAIL lr. and go to the next iteration.FAIL LR_AUTO lr. If called from within a block iteration.AND_CONTINUE lr. and not the global iteration.EXIT_VUSER_ AFTER_ITERATION Run until the end of the current iteration and then exit. LR_EXIT_VUSER_ AFTER_ITERATION lr.